commit-graph: update design document
As it exists right now, the commit-graph feature may provide inconsistent results when combined with commit grafts, replace objects, and shallow clones. Update the design document to discuss why these interactions are difficult to reconcile and how we will avoid errors by preventing updates to and reads from the commit-graph file when these other features exist. Signed-off-by: Derrick Stolee <dstolee@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Derrick Stolee committed
Aug 20, 2018 at 18:24 UTC
950c62bda208790e223230a73ce6c19ae8f9177b
1 file changed
+15
-3
Documentation/technical/commit-graph.txt
+15
-3
@@ -112,12 +112,24 @@ Design Details
112
- The file format includes parameters for the object ID hash function,
113
so a future change of hash algorithm does not require a change in format.
114
115
+- Commit grafts and replace objects can change the shape of the commit
116
+ history. The latter can also be enabled/disabled on the fly using
117
+ `--no-replace-objects`. This leads to difficultly storing both possible
118
+ interpretations of a commit id, especially when computing generation
119
+ numbers. The commit-graph will not be read or written when
120
+ replace-objects or grafts are present.
121
+
122
+- Shallow clones create grafts of commits by dropping their parents. This
123
+ leads the commit-graph to think those commits have generation number 1.
124
+ If and when those commits are made unshallow, those generation numbers
125
+ become invalid. Since shallow clones are intended to restrict the commit
126
+ history to a very small set of commits, the commit-graph feature is less
127
+ helpful for these clones, anyway. The commit-graph will not be read or
128
+ written when shallow commits are present.
129
+
130
Future Work
131
-----------
132
118
-- The commit graph feature currently does not honor commit grafts. This can
119
- be remedied by duplicating or refactoring the current graft logic.
120
-
133
- After computing and storing generation numbers, we must make graph
134
walks aware of generation numbers to gain the performance benefits they
135
enable. This will mostly be accomplished by swapping a commit-date-ordered