Chapter 43: Git Revisions Syntax

Section 43.1: Specifying revision by object name

$ git show da

e86e1950b1277e545cee180551750029cfe735 $ git show dae86e19

You can specify a revision using the SHA-1 object name, either the full 40-byte hexadecimal string or a unique substring.

Section 43.2: Symbolic ref names: branches, tags, remote-tracking branches

$ git log mas

ter # specify branch $ git show v1.0 # specify tag $ git show HEAD # specify current branch $ git show origin # specify default remote-tracking branch for remote 'origin'

You can specify a revision using a symbolic ref name, including branches (‘master’, ‘next’, ‘maint’), tags (‘v1.0’, ‘v0.6.3-rc2’), remote-tracking branches (‘origin’, ‘origin/master’), and special refs such as ‘HEAD’ for the current branch.

If the symbolic ref name is ambiguous, you need to specify the kind of ref you want to use:

$ git show heads/fix # specify branch
$ git show tags/fix # specify tag

Section 43.3: The default revision: HEAD

$ git show # 

equivalent to 'git show HEAD'

‘HEAD’ refers to the commit on which you based the changes in the working tree and is usually the symbolic name for the current branch. If a revision parameter is missing, many commands default to ‘HEAD’.

Section 43.4: Reflog references: <refname>@{<n>}

$ git show @{

1} # uses reflog for the current branch $ git show master@{1} # uses reflog for branch 'master' $ git show HEAD@{1} # uses 'HEAD' reflog

A ref, usually a branch or HEAD, followed by the suffix ‘@’ with an ordinal specification enclosed in braces (e.g., {1}, {15}), specifies the nth prior value of that ref in your local repository. You can check recent reflog entries with the git reflog command.

Section 43.5: Reflog references: <refname>@{<date>}

$ git show ma

ster@{yesterday} $ git show HEAD@{5 minutes ago} # or HEAD@{5.minutes.ago}

A ref followed by the suffix ‘@’ with a date specification enclosed in braces (e.g., {yesterday}, {1 month 2 weeks 3 days 1 hour 1 second ago}, or {1979-02-26 18:30:00}) specifies the value of the ref at a prior point in time. You can use git reflog with a date specifier to look up the exact time when you did something to a given ref in the local repository.

Section 43.6: Tracked / upstream branch: <branchname>@{upstream}

$ git log @{u

pstream}.. # what was done locally and not yet published, current branch $ git show master@{upstream} # show upstream of branch 'master'

The suffix ‘@{upstream}’ (or short form ‘@{u}’) appended to a branch name refers to the branch that the specified branch is set to build on top of. It is useful to see the commits your branch is ahead of upstream and the commits you are behind.

To see commits ahead of upstream:

$ git log --oneline @{u}

Section 43.7: Commit Ancestry Chain: <rev>^, <rev>~<n>, etc

$ git reset -

-hard HEAD^ # discard last commit $ git rebase --interactive HEAD~5 # rebase last 4 commits

A suffix ‘^’ to a revision parameter means the first parent of that commit object. ‘^<n>’ means the nth parent (i.e., <rev>^ is equivalent to <rev>^1).

A suffix ‘~<n>’ to a revision parameter means the commit object that is the nth generation ancestor of the named commit object, following only the first parents. For example, <rev>3 is equivalent to <rev>^^^. The shortcut <rev> is equivalent to <rev>~1, which is equivalent to <rev>^1 or simply <rev>^.

Section 43.8: Dereferencing Branches and Tags: <rev>^0, <rev>^{<type>} In some cases, the behavior of a command depends on whether it is given a branch name, tag name, or an arbitrary revision. “De-referencing” syntax can be used if the latter is needed.

A suffix ‘^’ followed by an object type name (tag, commit, tree, blob) enclosed in braces (e.g., v0.99.8^{commit}) means to dereference the object at <rev> recursively until an object of type <type> is found or the object cannot be dereferenced anymore. <rev>^0 is a shorthand for <rev>^{commit}.

$ git checkout HEAD^0 # equivalent to 'git checkout --detach' in modern Git

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

Compare:

$ git show v1.0
$ git cat-file -p v1.0
$ git replace --edit v1.0

with:

$ git show v1.0^{}
$ git cat-file -p v1.0^{}
$ git replace --edit v1.0^{}

Section 43.9: Youngest Matching Commit: <rev>^{/<text>}, :/<text>

$ git show HE

AD^{/fix nasty bug} # find starting from HEAD $ git show ':/fix nasty bug' # find starting from any branch

A colon (‘:’), followed by a slash (‘/’), followed by a text, names a commit whose commit message matches the specified regular expression. This name returns the youngest matching commit reachable from any ref.

The regular expression can match any part of the commit message. To match messages starting with a string, one can use, for example, :/^foo. The special sequence :/! is reserved for modifiers to what is matched. :/!-foo performs a negative match, while :/!!foo matches a literal ‘!’ character followed by ‘foo’.

A suffix ‘^’ to a revision parameter, followed by a brace pair that contains a text led by a slash, is the same as the :/<text> syntax, returning the youngest matching commit reachable from the <rev> before ‘^’.