gitversion-controlterminology

What is the difference between a commit and a revision in Git?

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?

Solution

  • 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:

    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.