| 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. |