1Shallow commits 2=============== 3 4.Definition 5********************************************************* 6Shallow commits do have parents, but not in the shallow 7repo, and therefore grafts are introduced pretending that 8these commits have no parents. 9********************************************************* 10 11$GIT_DIR/shallow lists commit object names and tells Git to 12pretend as if they are root commits (e.g. "git log" traversal 13stops after showing them; "git fsck" does not complain saying 14the commits listed on their "parent" lines do not exist). 15 16Each line contains exactly one SHA-1. When read, a commit_graft 17will be constructed, which has nr_parent < 0 to make it easier 18to discern from user provided grafts. 19 20Note that the shallow feature could not be changed easily to 21use replace refs: a commit containing a `mergetag` is not allowed 22to be replaced, not even by a root commit. Such a commit can be 23made shallow, though. Also, having a `shallow` file explicitly 24listing all the commits made shallow makes it a *lot* easier to 25do shallow-specific things such as to deepen the history. 26 27Since fsck-objects relies on the library to read the objects, 28it honours shallow commits automatically. 29 30There 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 51To make a shallow clone, you can call "git-clone --depth 20 repo". 52The result contains only commit chains with a length of at most 20. 53It also writes an appropriate $GIT_DIR/shallow. 54 55You can deepen a shallow repository with "git-fetch --depth 20 56repo branch", which will fetch branch from repo, but stop at depth 5720, updating $GIT_DIR/shallow. 58 59The special depth 2147483647 (or 0x7fffffff, the largest positive 60number a signed 32-bit integer can contain) means infinite depth.