What is a Git Revision Expression?

Question

So, I am using Git GUI to make a repository. But I cant find ANY trace on Google, the Documentation, or anywhere else what a 'Revision Expression' is, and it is required to create a new Branch.

Also, it seems that this is used many other places in the program, so I belive it is important to know.

I did find a question on this on StackOverflow, but the guy never got an answer.

I just need to know: What is a Revision Expression?

Answer 1

git needs to be able to identify a commit during a number of common operations

https://git-scm.com/docs/git-rev-parse

There are a number of ways to identify a commit. You could use a branch, tag, commit sha1, or expressions. For example:

git log HEAD 

HEAD eventually resolves to a specific commit, and you will be given the log for that. YOu could also say:

git log master 

master is a branch, and that will also resolve to a specific commit.

git log fd72e9c99312 

Now that IS the actual commit.

---

The below documentation is what you are looking for. Taken from the git-rev-parse command documentation at http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html.

SPECIFYING REVISIONS

A revision parameter typically, but not necessarily, names a commit object. They use what is called an extended SHA1 syntax. Here are various ways to spell object names. The ones listed near the end of this list are to name trees and blobs contained in a commit.

The full SHA1 object name (40-byte hexadecimal string), or a substring of such that is unique within the repository. E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both name the same commit object if there are no other object in your repository whose object name starts with dae86e.

An output from git-describe; i.e. a closest tag, optionally followed by a dash and a number of commits, followed by a dash, a g, and an abbreviated object name.

A symbolic ref name. E.g. master typically means the commit object referenced by $GIT_DIR/refs/heads/master. If you happen to have both heads/master and tags/master, you can explicitly say heads/master to tell git which one you mean. When ambiguous, a is disambiguated by taking the first match in the following rules:

if $GIT_DIR/ exists, that is what you mean (this is usually useful only for HEAD, FETCH_HEAD, ORIG_HEAD and MERGE_HEAD);

otherwise, $GIT_DIR/refs/ if exists;

otherwise, $GIT_DIR/refs/tags/ if exists;

otherwise, $GIT_DIR/refs/heads/ if exists;

otherwise, $GIT_DIR/refs/remotes/ if exists;

otherwise, $GIT_DIR/refs/remotes//HEAD if exists.

HEAD names the commit your changes in the working tree is based on. FETCH_HEAD records the branch you fetched from a remote repository with your last git-fetch invocation. ORIG_HEAD is created by commands that moves your HEAD in a drastic way, to record the position of the HEAD before their operation, so that you can change the tip of the branch back to the state before you ran them easily. MERGE_HEAD records the commit(s) you are merging into your branch when you run git-merge.

A ref followed by the suffix @ with a date specification enclosed in a brace pair (e.g. {yesterday}, {1 month 2 weeks 3 days 1 hour 1 second ago} or {1979-02-26 18:30:00}) to specify the value of the ref at a prior point in time. This suffix may only be used immediately following a ref name and the ref must have an existing log ($GIT_DIR/logs/). Note that this looks up the state of your local ref at a given time; e.g., what was in your local master branch last week. If you want to look at commits made during certain times, see --since and --until.

A ref followed by the suffix @ with an ordinal specification enclosed in a brace pair (e.g. {1}, {15}) to specify the n-th prior value of that ref. For example master@{1} is the immediate prior value of master while master@{5} is the 5th prior value of master. This suffix may only be used immediately following a ref name and the ref must have an existing log ($GIT_DIR/logs/).

You can use the @ construct with an empty ref part to get at a reflog of the current branch. For example, if you are on the branch blabla, then @{1} means the same as blabla@{1}.

The special construct @{-} means the th branch checked out before the current one.

A suffix ^ to a revision parameter means the first parent of that commit object. ^ means the th parent (i.e. rev^ is equivalent to rev^1). As a special rule, rev^0 means the commit itself and is used when rev is the object name of a tag object that refers to a commit object.

A suffix ~ to a revision parameter means the commit object that is the th generation grand-parent of the named commit object, following only the first parent. I.e. rev~3 is equivalent to rev^^^ which is equivalent to rev^1^1^1. See below for a illustration of the usage of this form.

A suffix ^ followed by an object type name enclosed in brace pair (e.g. v0.99.8^{commit}) means the object could be a tag, and dereference the tag recursively until an object of that type is found or the object cannot be dereferenced anymore (in which case, barf). rev^0 introduced earlier is a short-hand for rev^{commit}.

A suffix ^ followed by an empty brace pair (e.g. v0.99.8^{}) means the object could be a tag, and dereference the tag recursively until a non-tag object is found.

A colon, followed by a slash, followed by a text: this names a commit whose commit message starts with the specified text. This name returns the youngest matching commit which is reachable from any ref. If the commit message starts with a !, you have to repeat that; the special sequence :/!, followed by something else than ! is reserved for now.

A suffix : followed by a path; this names the blob or tree at the given path in the tree-ish object named by the part before the colon.

A colon, optionally followed by a stage number (0 to 3) and a colon, followed by a path; this names a blob object in the index at the given path. Missing stage number (and the colon that follows it) names a stage 0 entry. During a merge, stage 1 is the common ancestor, stage 2 is the target branch's version (typically the current branch), and stage 3 is the version from the branch being merged.

Here is an illustration, by Jon Loeliger. Both commit nodes B and C are parents of commit node A. Parent commits are ordered left-to-right.

G   H   I   J  \ /     \ /   D   E   F    \  |  / \     \ | /   |      \|/    |       B     C        \   /         \ /          A A =      = A^0 B = A^   = A^1     = A~1 C = A^2  = A^2 D = A^^  = A^1^1   = A~2 E = B^2  = A^^2 F = B^3  = A^^3 G = A^^^ = A^1^1^1 = A~3 H = D^2  = B^^2    = A^^^2  = A~2^2 I = F^   = B^3^    = A^^3^ J = F^2  = B^3^2   = A^^3^2 

Answer 2

gahooa gives the comprehensive answer. The common case:

• Name of an existing branch (e.g., master)
• First few digits of a SHA1 checksum, best captured from gitk or git log

Welcome to the wonderful world of git. TMI is par for the course...