Support git's ancestry syntax
Proposal
Currently in GFM, you can refer to a commit hash itself (e.g. dd760dcb), you can directly diff 2 commits together (e.g. 431c4042..dd760dcb), and you can diff over a commit range (e.g. 6fd3481b...dd760dcb). However, this is kinda limited, and sometimes it's better to have more control over what the diff describes.
Git supports many other ways of referring to commit hashes, and commits in general, that many find useful. These are the most common:
| Syntax | Description |
|---|---|
<commit>^ |
Gets the parent of a commit. Useful for describing a range that includes the first commit w/o specifying (e.g. <commit a>^...<commit b> produces a range from a to b that includes a) |
<commit>~ |
Gets the 1st parent of a commit. Equivalent to <commit>^, but is more often used with refs (like HEAD~) than with diffs |
<commit>^n |
Gets the nth parent of a commit. Useful for merges, when a commit might have multiple parents |
<commit>~n |
Gets the nth-order parent of a commit. Useful for describing commits relative to an earlier commit in the commit history |
Adding support for these kinds of commit references would involve changing most endpoints that reference commits to allow for this syntax to be used in the URL. For example, wherever <commit> is mentioned in the following endpoints, the above syntax would need to be supported:
/<project>/-/commit/<commit>-
/<project>/-/compare/<commit>..<commit>and/<project>/-/compare/<commit>...<commit> /<project>/-/blame/<commit>/<path to resource>/<project>/-/blob/<commit>/<path to resource>
This supports the following use cases:
- Often users might fork a project and make a few commits adding a feature or fixing a bug before opening an MR. This happens most often when the user doesn't have write access to the repository, and couldn't create branches themselves. When this happens, the user might want to make the first commit establish the intent of the following commits, which would actually implement the solution. This happens pretty often, surprisingly (for example, kingjan1999/gitlab-ee@d0a26461 and proceeding commits kingjan1999/gitlab-ee@d0a26461...325d7e46), and in these cases it makes more sense to describe these commits relative to the intent-establishing one.
- When describing commit ranges, it often feels more natural for each end of the range to both be inclusive (e.g.
[1, 3]as opposed to(1, 3]). This is because often the commits that the user cares about are the first commit implementing a change and the last commit implementing a change. When describing this range, it makes more sense to follow this convention, even if it means including a strange looking character, because the hashes of the commits that we care about are displayed instead of the hashes of commits that we don't really care as much about. This is doubly important for newer git users, who might google how to describe commit ranges inclusively, find someone using the ancestry syntax (<commit>^and<commit>~), and be confused about why they can't replicate that in GFM and gitlab's tools. - It would make talking commits across branches much easier! Instead of tracking things down and copying references,
you could just combine these syntaxes into a compound thought (
<commit>^2~3is something like "3 commits into the 2nd parent's history"). This might make collaboration around MR's a bit easier.
It should be noted that github does support ^ syntax with diffs, but doesn't support it in github markdown. This could
be a path we go down, if we think that it might cause too much confusion, but I think that there's a lot of utility to
supporting this in gitlab markdown as well.
Relevant Links: