338

What does git rev-parse do?

I have read the man page but it raised more questions than answers. Things like:

Pick out and massage parameters

Massage? What does that mean?

I'm using as a resolver (to SHA1) of revision specifiers, like

git rev-parse HEAD^

or

git rev-parse origin/master

Is this the command’s purpose? If not, is even correct to use it to achieve this?

joe
  • 2,305
  • 2
  • 14
  • 25
talles
  • 11,195
  • 8
  • 39
  • 55
  • 3
    As far as I can see in the man page, it's a mostly internal utility to parse revision/object names for other commands. What you're doing is pretty much the purpose of the `rev-parse` command. You can also use it to normalize a command line, so that the actual program doesn't have to understand the complicated object name syntax of Git (you'd use `git rev-parse` to change, or "massage", certain parameters in the command line before the actual program is called). –  Apr 03 '13 at 22:16
  • See also https://github.com/git/git/commit/b2a2c4d8099c69ec997e51cac489c0947ad17956 – VonC Oct 14 '17 at 23:09
  • 85
    The man page for `git rev-parse` is laughably incomprehensible. I'm surprised nobody has bothered to rewrite that jargon into something human readable, even after 5 years. – not2qubit Mar 25 '18 at 08:10
  • 3
    @not2qubit Me: 'Thank you for clarifying, I was feeling inferior.' Linus Torvalds: 'I re-read it, exactly what part did you not comprehend?' – Brain2000 Jun 12 '20 at 15:16

3 Answers3

294

git rev-parse is an ancillary plumbing command primarily used for manipulation.

One common usage of git rev-parse is to print the SHA1 hashes given a revision specifier. In addition, it has various options to format this output such as --short for printing a shorter unique SHA1.

There are other use cases as well (in scripts and other tools built on top of git) that I've used for:

  • --verify to verify that the specified object is a valid git object.
  • --git-dir for displaying the abs/relative path of the the .git directory.
  • Checking if you're currently within a repository using --is-inside-git-dir or within a work-tree using --is-inside-work-tree
  • Checking if the repo is a bare using --is-bare-repository
  • Printing SHA1 hashes of branches (--branches), tags (--tags) and the refs can also be filtered based on the remote (using --remote)
  • --parse-opt to normalize arguments in a script (kind of similar to getopt) and print an output string that can be used with eval

Massage just implies that it is possible to convert the info from one form into another i.e. a transformation command. These are some quick examples I can think of:

  • a branch or tag name into the commit's SHA1 it is pointing to so that it can be passed to a plumbing command which only accepts SHA1 values for the commit.
  • a revision range A..B for git log or git diff into the equivalent arguments for the underlying plumbing command as B ^A
brg
  • 7,332
  • 8
  • 44
  • 60
Tuxdude
  • 40,779
  • 13
  • 96
  • 102
126

Just to elaborate on the etymology of the command name rev-parse, Git consistently uses the term rev in plumbing commands as short for "revision" and generally meaning the 40-character SHA1 hash for a commit. The command rev-list for example prints a list of 40-char commit hashes for a branch or whatever.

In this case the name might be expanded to parse-a-commitish-to-a-full-SHA1-hash. While the command has the several ancillary functions mentioned in Tuxdude's answer, its namesake appears to be the use case of transforming a user-friendly reference like a branch name or abbreviated hash into the unambiguous 40-character SHA1 hash most useful for many programming/plumbing purposes.

I know I was thinking it was "reverse-parse" something for quite a while before I figured it out and had the same trouble making sense of the terms "massaging" and "manipulation" :)

Anyway, I find this "parse-to-a-revision" notion a satisfying way to think of it, and a reliable concept for bringing this command to mind when I need that sort of thing. Frequently in scripting Git you take a user-friendly commit reference as user input and generally want to get it resolved to a validated and unambiguous working reference as soon after receiving it as possible. Otherwise input translation and validation tends to proliferate through the script.

scanny
  • 20,022
  • 3
  • 40
  • 66
  • 10
    Thanks for the explanation, I didn't understand the git-docs one bit: http://git-scm.com/docs/git-rev-parse – Jacob McKay Aug 01 '15 at 19:51
  • can you give us an example of `messaging` and `manipulation` as you allude to before? – Bo Chen Apr 30 '18 at 01:03
  • 5
    In other words, `git rev-parse` is short for `git revision-parse`. It takes the given input and returns the corresponding 40-character revision ID. – Jonathan Benn Nov 22 '18 at 19:14
  • 2
    git doc itself is like plumbing, and this answer is the porcelain. – David Chen Jul 30 '20 at 04:33
  • Wow, it turns out that `git rev-parse` is actually extremely simple to understand. Why is the manual page written in such hieroglyphics? – GMA Mar 01 '21 at 14:30
44

git rev-parse Also works for getting the current branch name using the --abbrev-ref flag like:

git rev-parse --abbrev-ref HEAD
David Chen
  • 1,473
  • 2
  • 9
  • 21
mitra
  • 629
  • 5
  • 9