[go: up one dir, main page]
Skip to content

GFM should support all refs, not just hashes

Proposal

Currently, GFM has the capability to render git hashes. However when wanting to reference a branch or a tag, this no longer works.

To make this more user-friendly, the proposal is to add the moniker git: to indicate that we want to references git-ness. e.g. git:v13.7.0-rc3-ee would link to the actual tag https://gitlab.com/gitlab-org/gitlab/-/tags/v13.7.0-rc3-ee and render it as [v13.7.0-rc3-ee](/-/tags/v13.7.0-rc3-ee). Further more, the feature should support different namespaces, e.g. git:<other/namespace>/v13.7.0-rc3-ee] should equally work. To differentiate between going to the tag and going to the git-tree of the tag, a trailing slash can be used. e.g. git:v13.7.0-rc3-ee/ renders as [v13.7.0-rc3-ee](/-/tree/v13.7.0-rc3-ee).

This should work for all kinds of git refs, tags, branches and hashes. As such just having a hash could become an alias to git:b0ec53557378ada making the interface nice and consize, while still keeping backwards compatibility.

Quite likely, should this feature also support linking to files, which would be inherent anyway, but best mention it explicitly. Thus: git:master/VERSION#L1 would link to the master branch, file VERSION on Line 1. To link to the master branch of a repo, git:/VERSION#1 or git:<namespace>/VERSION#1 would do exactly that (e.g. it points to the root via the leading slash). Using any other ref would work of course as well, where a commit hash, would render the commit.

It would be nice if both invocations would work, in text and as link destination. e.g.

This code is on `git:master/src/`

would expand into a link as described, but doing

This code is on [master](git:master/src)

Would still expand but not enter a URL in a URL. The most important reason for having this is of course that it happily surives URL changes and local namespace changes. For remote namespaces, this will of course break, unless gitlab auto-updates namespace references (big feature, for all wiki sed :p).

In summary:

Edited by Olliver Schinagl