technical/shallow.txt

   1 Shallow commits
   2 ===============
   3
   4 .Definition
   5 *********************************************************
   6 Shallow commits do have parents, but not in the shallow
   7 repo, and therefore grafts are introduced pretending that
   8 these commits have no parents.
   9 *********************************************************
  10
  11 $GIT_DIR/shallow lists commit object names and tells Git to
  12 pretend as if they are root commits (e.g. "git log" traversal
  13 stops after showing them; "git fsck" does not complain saying
  14 the commits listed on their "parent" lines do not exist).
  15
  16 Each line contains exactly one object name. When read, a commit_graft
  17 will be constructed, which has nr_parent < 0 to make it easier
  18 to discern from user provided grafts.
  19
  20 Note that the shallow feature could not be changed easily to
  21 use replace refs: a commit containing a `mergetag` is not allowed
  22 to be replaced, not even by a root commit. Such a commit can be
  23 made shallow, though. Also, having a `shallow` file explicitly
  24 listing all the commits made shallow makes it a *lot* easier to
  25 do shallow-specific things such as to deepen the history.
  26
  27 Since fsck-objects relies on the library to read the objects,
  28 it honours shallow commits automatically.
  29
  30 There are some unfinished ends of the whole shallow business:
  31
  32 - maybe we have to force non-thin packs when fetching into a
  33   shallow repo (ATM they are forced non-thin).
  34
  35 - A special handling of a shallow upstream is needed. At some
  36   stage, upload-pack has to check if it sends a shallow commit,
  37   and it should send that information early (or fail, if the
  38   client does not support shallow repositories). There is no
  39   support at all for this in this patch series.
  40
  41 - Instead of locking $GIT_DIR/shallow at the start, just
  42   the timestamp of it is noted, and when it comes to writing it,
  43   a check is performed if the mtime is still the same, dying if
  44   it is not.
  45
  46 - It is unclear how "push into/from a shallow repo" should behave.
  47
  48 - If you deepen a history, you'd want to get the tags of the
  49   newly stored (but older!) commits. This does not work right now.
  50
  51 To make a shallow clone, you can call "git-clone --depth 20 repo".
  52 The result contains only commit chains with a length of at most 20.
  53 It also writes an appropriate $GIT_DIR/shallow.
  54
  55 You can deepen a shallow repository with "git-fetch --depth 20
  56 repo branch", which will fetch branch from repo, but stop at depth
  57 20, updating $GIT_DIR/shallow.
  58
  59 The special depth 2147483647 (or 0x7fffffff, the largest positive
  60 number a signed 32-bit integer can contain) means infinite depth.