39

There are a number of git commands, such as git clone --depth 10 <repo>, that require the number of revisions [git help revisions] to be given.

What is the distinction between a commit and a revision (in git, rather than say svn)?

Or does it only show up in the plural when trying to count revisions/commits, e.g. that revisons must be counted by walking the DAG (directed acyclic graph) of commits and their parents, or some other careful distinction?

Arad Alvand
  • 8,607
  • 10
  • 51
  • 71
Philip Oakley
  • 13,333
  • 9
  • 48
  • 71

2 Answers2

25

See "SPECIFYING REVISIONS" of git rev-parse:

A revision parameter <rev> typically, but not necessarily, names a commit object.
It uses what is called an extended SHA1 syntax, [and includes] various ways to spell object names.

So "revision" refers to the id you can use as a parameter to reference an object in git (usually a commit).

HEAD@{5 minutes ago} is a revision which reference the commit present 5 minutes ago.

gitrevision mentions:

[...] some Git commands (such as git show) also take revision parameters which denote other objects than commits, e.g. blobs ("files") or trees ("directories of files").

For instance, the following rev parameter doesn't reference a commit:

<rev>:<path>, e.g. HEAD:README, :README, master:./README

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

A "commit" in Git generally designates a "commit object" (as described in git commit-tree for instance):

A commit encapsulates:

  • all parent object ids
  • author name, email and date
  • committer name and email and the commit time.

So:

  • a commit designates one of the git objects (others are blobs, tree, tags, notes),
  • a revision is a way to reference a git object.

In your case (git clone) --depth <n> does:

Create a shallow clone with a history truncated to the specified number of revisions.

It is for all the commits accessible at that depth, up to n revisions per path in the DAG.
Since the result can be more than n commits, the term revision is more adapted here in order to emphasize you don't want just n commits, but any commits referenced by a max of n revisions accessible.

However, in this context, revisions clearly reference only commits (as illustrated below) reachable (as you mentioned in "Is git clone --depth 1 (shallow clone) more useful than it makes out?").

The question is "reachable from what"?

You referenced this thread which included:

IIRC, --depth=<n> is not "deepen by <n>", but "make sure I have at least <n> from the updated tip(s)".
The shallow-clone hack gives you quite useless (even though it may be internally consistent) semantics if you shallow-cloned way in the past and fetched with --depth after the other side added many more commits than <n>, as you cannot guess what the right value of <n> should be without actually fetching without --depth.

Community
  • 1
  • 1
VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • C: so in that sense a specific (this) revision always resolves to a specific (that) commit, a one-to-one (one way) mapping, though the map may change as time progresses and new commits are added. From that view point revisions are the multiplicity of ways to specify a particular commit. I was interested the use of a revision count aspect of the plural. – Philip Oakley Aug 03 '12 at 09:24
  • @PhilipOakley ok, I have edited the answer to use the distinction I have made in the context of `git clone` (which uses the work "`revision`" only once) – VonC Aug 03 '12 at 09:49
  • It might be useful if you could give an example of a revision that doesn't name a commit object? I may misunderstand, but I can't see that from your answer. – Mark Longair Aug 03 '12 at 13:31
  • @Mark, I'm happy that 'a revision' points at 'a commit'. The question was really about revisions in the plural, that may be given by ranges and depths, and how to avoid any confusion about what is included in the selection (I've seen the shallow clone `depth` confusion comes up a few times) – Philip Oakley Aug 03 '12 at 14:43
  • @PhilipOakley do you have an example of such a confusion regarding the `--depth` parameter of a shallow clone? – VonC Aug 03 '12 at 15:14
  • (+1) thanks - it seems needlessly confusing to me to still call references to blobs and trees "revisions", but there you go. @PhilOakley: I was just asking because of the sentence VonC quoted saying, "A revision parameter typically, but not necessarily, names a commit object." – Mark Longair Aug 03 '12 at 16:07
  • @MarkLongair agreed (on the confusion part), but that's how revisions are presented in git revision (http://git-scm.com/docs/gitrevisions.html). I think the distinction "reference to a git object" ("revision") vs. one of the actual objects (like "commit") is key here. – VonC Aug 03 '12 at 16:32
  • @VonC, I did notice that there is no reference to `--depth` in `git revisions`, nor in `git rev-list`, which has a lot of options. The latter from my other question http://stackoverflow.com/a/11795549/717355. A bit more search did find it in `git fetch` and `pull`, where it talks of commits rather than revisions, and of deepening (but you can't deepen a clone, it's always counted from zero ;-). – Philip Oakley Aug 04 '12 at 20:25
5

Interesting. I hadn't come across this distinction before but from skimming the documentation and my own experience, a commit in git is an object that points to a specific point in time in the history of the project (along with information on how it reached there). A revision is superset of this that talks about different ways to reference a commit or a range of commits.

Noufal Ibrahim
  • 71,383
  • 13
  • 135
  • 169
  • I was think more in terms of the 'counted' view of a revision (e.g. 5 revisons), rather than the (very) many ways of describing exactly the same revison! ;-) – Philip Oakley Aug 03 '12 at 09:11