commit-graph.txt: update design document
We now calculate generation numbers in the commit-graph file and use them in paint_down_to_common(). Expand the section on generation numbers to discuss how the three special generation numbers GENERATION_NUMBER_INFINITY, _ZERO, and _MAX interact with other generation numbers. Signed-off-by: Derrick Stolee <dstolee@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Derrick Stolee committed
May 1, 2018 at 12:47 UTC
1472978ec670e57913836dcc98ba9cf560d94a1c
1 file changed
+24
-5
Documentation/technical/commit-graph.txt
+24
-5
@@ -77,6 +77,29 @@ in the commit graph. We can treat these commits as having "infinite"
77
generation number and walk until reaching commits with known generation
78
number.
79
80
+We use the macro GENERATION_NUMBER_INFINITY = 0xFFFFFFFF to mark commits not
81
+in the commit-graph file. If a commit-graph file was written by a version
82
+of Git that did not compute generation numbers, then those commits will
83
+have generation number represented by the macro GENERATION_NUMBER_ZERO = 0.
84
+
85
+Since the commit-graph file is closed under reachability, we can guarantee
86
+the following weaker condition on all commits:
87
+
88
+ If A and B are commits with generation numbers N amd M, respectively,
89
+ and N < M, then A cannot reach B.
90
+
91
+Note how the strict inequality differs from the inequality when we have
92
+fully-computed generation numbers. Using strict inequality may result in
93
+walking a few extra commits, but the simplicity in dealing with commits
94
+with generation number *_INFINITY or *_ZERO is valuable.
95
+
96
+We use the macro GENERATION_NUMBER_MAX = 0x3FFFFFFF to for commits whose
97
+generation numbers are computed to be at least this value. We limit at
98
+this value since it is the largest value that can be stored in the
99
+commit-graph file using the 30 bits available to generation numbers. This
100
+presents another case where a commit can have generation number equal to
101
+that of a parent.
102
+
103
Design Details
104
--------------
105
@@ -98,18 +121,14 @@ Future Work
121
- The 'commit-graph' subcommand does not have a "verify" mode that is
122
necessary for integration with fsck.
123
101
-- The file format includes room for precomputed generation numbers. These
102
- are not currently computed, so all generation numbers will be marked as
103
- 0 (or "uncomputed"). A later patch will include this calculation.
104
-
124
- After computing and storing generation numbers, we must make graph
125
walks aware of generation numbers to gain the performance benefits they
126
enable. This will mostly be accomplished by swapping a commit-date-ordered
127
priority queue with one ordered by generation number. The following
128
operations are important candidates:
129
111
- - paint_down_to_common()
130
- 'log --topo-order'
131
+ - 'tag --merged'
132
133
- Currently, parse_commit_gently() requires filling in the root tree
134
object for a commit. This passes through lookup_tree() and consequently