[v3,0/4] Add some Glossary of terms information

Message

Philip Oakley Oct. 29, 2022, 4:41 p.m. UTC

(in reply to <[e-mail]>

This short series looks to add the basics of the reachability bitmap
and commit graph phrases to the glossary of terms. While these
techniques are well known to their developers, for some, they are
just magic phrases.

[V3] .. since V2

1/4 Unchanged.
2/4 The distinction between the generic 'commit graph' of the DAG and
the implementation specifics of 'commit-graph' file has been retained
for the glossary. 
However the deliberate hyphenation has been included, and a fourth patch
added to maintain the consistency of 'commit-graph' in other documents.

3/4 Tweaks & links applied to Reachability patch.
4/4 New - maintain the consistency of 'commit-graph' in other documents.

[V2] .. since V1
was GitGitGadget #1282,
(in reply to <[e-mail]>)
Patch 4/4 has been taken upstream independently, and hence dropped
here so we're now just [n/3].

Patch 1/3 Dropped the glossary addition in favour of changing the
locations that used ODB (Junio's suggestion). Kept the git
pack-redundant's `--alt-odb` but spelt out 'object database' in full
in the man page. The only remaining `odb`s are within `goodbye` ;-).

While here, add the (oid) abbreviation to its adjacent entry.

Patch 2/3 Split the 'commit-graph' explanation into two parts to
distinguish the speed-up option, from Git's core graph concept of
object traversal. Included links to existing terms.

Patch 3/3 Added links to existing terms. Statement for the
reachability bitmaps.

added cc: for Stolee (commit-graph) and Abhradeep Chakraborty
(Bitmaps) review.


[V1] [GGG PR #1282] 
https://lore.kernel.org/git/[e-mail]/

The first patch [1/4] is to show OBD as an abbreviation to avoid a UNA [0]

Patch [2/4] provides a basic statement for the Commit-Graph's purpose.

Patch [3/4] provides a similar statement for the reachability bitmaps.

These two patches maybe misses out on some linking information as to
the benefits these have and the basics of their heuristic.

Patch [4/4] follows up on a bug report about the lack of idempotence
for the `--renormalise' command. See commit message for details.

[0] UNA Un-Named Abbreviation.

Signed-off-by: Philip Oakley [e-mail]
cc: Philip Oakley [e-mail]


Philip Oakley (4):
  doc: use 'object database' not ODB or abbreviation
  glossary: add "commit graph" description
  glossary: add reachability bitmap description
  doc: use "commit-graph" hyphenation consistently

 Documentation/config/core.txt                 |  2 +-
 Documentation/git-pack-redundant.txt          |  2 +-
 Documentation/gitformat-commit-graph.txt      |  6 ++---
 Documentation/glossary-content.txt            | 27 +++++++++++++++++--
 Documentation/technical/commit-graph.txt      |  8 +++---
 Documentation/technical/parallel-checkout.txt |  2 +-
 6 files changed, 35 insertions(+), 12 deletions(-)

Range-diff against remotes/gitster/po/glossary-around-traversal (v2?):
1:  de164ab78b ! 1:  748b15345e doc: use 'object database' not ODB or abbreviation
    @@ Commit message
         abbreviation to its entry.
     
         Signed-off-by: Philip Oakley <[e-mail]>
    -    Signed-off-by: Junio C Hamano <[e-mail]>
     
      ## Documentation/git-pack-redundant.txt ##
     @@ Documentation/git-pack-redundant.txt: OPTIONS
2:  f677d57699 ! 2:  052a9568e7 glossary: add "commit graph" description
    @@ Commit message
         glossary: add "commit graph" description
     
         Git has an additional "commit graph" capability that supplements the
    -    normal commit object's directed acylic graph (DAG). The supplemental
    +    normal commit object's directed acyclic graph (DAG). The supplemental
         commit graph file is designed for speed of access.
     
         Describe the commit graph both from the normative DAG view point and
    @@ Commit message
         by linking to the `ref` glossary entry, matching this commit graph
         entry.
     
    +    The commit-graph file is also distinguished by its hyphenation.
    +
    +    Subsequent commit catches the few cases where the hyphenation of
    +    commit-graph was missing.
    +
         Signed-off-by: Philip Oakley <[e-mail]>
    -    Signed-off-by: Junio C Hamano <[e-mail]>
     
      ## Documentation/glossary-content.txt ##
     @@
    @@ Documentation/glossary-content.txt: state in the Git history, by creating a new
      to point at the new commit.
      
     +[[def_commit_graph_general]]commit graph concept, representations and usage::
    -+	A synonym for the <<def_DAG,DAG>> structure formed by
    -+	the commits in the object database, <<def_ref,referenced>> by branch tips,
    ++	A synonym for the <<def_DAG,DAG>> structure formed by the commits
    ++	in the object database, <<def_ref,referenced>> by branch tips,
     +	using their <<def_chain,chain>> of linked commits.
     +	This structure is the definitive commit graph. The
     +	graph can be represented in other ways, e.g. the
    -+	<<def_commit_graph_file,commit graph file>>.
    ++	<<def_commit_graph_file,"commit-graph" file>>.
     +
    -+[[def_commit_graph_file]]commit graph file::
    -+	The commit-graph file is a supplemental representation of
    -+	the <<def_commit_graph_general,commit graph>> which accelerates
    -+	commit graph walks. The "commit-graph" file is stored
    -+	either in the .git/objects/info directory or in the info directory
    -+	of an alternate object database.
    ++[[def_commit_graph_file]]commit-graph file::
    ++	The "commit-graph" (normally hyphenated) file is a supplemental
    ++	representation of the <<def_commit_graph_general,commit graph>>
    ++	which accelerates commit graph walks. The "commit-graph" file is
    ++	stored either in the .git/objects/info directory or in the info
    ++	directory of an alternate object database.
     +
      [[def_commit_object]]commit object::
      	An <<def_object,object>> which contains the information about a
3:  39e9a282fc ! 3:  d56234b70c glossary: add reachability bitmap description
    @@ Commit message
         Describe the purpose of the reachability bitmap.
     
         Signed-off-by: Philip Oakley <[e-mail]>
    -    Signed-off-by: Junio C Hamano <[e-mail]>
     
      ## Documentation/glossary-content.txt ##
     @@ Documentation/glossary-content.txt: exclude;;
    @@ Documentation/glossary-content.txt: exclude;;
      
     +[[def_reachability_bitmap]]reachability bitmaps::
     +	Reachability bitmaps store information about the
    -+	<<def_reachable,reachability>> of a selected set of objects in
    -+	a packfile, or a multi-pack index (MIDX) to speed up object search.
    -+	A repository may have at
    -+	most one bitmap. The bitmap may belong to either one pack, or the
    -+	repository's multi-pack index (if it exists).
    ++	<<def_reachable,reachability>> of a selected set of commits in
    ++	a packfile, or a multi-pack index (MIDX), to speed up object search.
    ++	The bitmaps are stored in a ".bitmap" file. A repository may have at
    ++	most one bitmap file in use. The bitmap file may belong to either one
    ++	pack, or the repository's multi-pack index (if it exists).
     +
      [[def_rebase]]rebase::
      	To reapply a series of changes from a <<def_branch,branch>> to a
-:  ---------- > 4:  87686e63f9 doc: use "commit-graph" hyphenation consistently

Comments

Taylor Blau Oct. 29, 2022, 5:24 p.m. UTC | #1

On Sat, Oct 29, 2022 at 05:41:08PM +0100, Philip Oakley wrote:
> (in reply to <[e-mail]>
>
> This short series looks to add the basics of the reachability bitmap
> and commit graph phrases to the glossary of terms. While these
> techniques are well known to their developers, for some, they are
> just magic phrases.

Thanks, the updated round looks good to me. I applied these on top of
the tip of master instead of the existing merge base (which was
dc8c8deaa6b (Prepare for 2.36.2, 2022-06-07)).

Will queue.

Thanks,
Taylor

Philip Oakley Oct. 29, 2022, 5:34 p.m. UTC | #2

On 29/10/2022 18:24, Taylor Blau wrote:
> On Sat, Oct 29, 2022 at 05:41:08PM +0100, Philip Oakley wrote:
>> (in reply to <[e-mail]>
>>
>> This short series looks to add the basics of the reachability bitmap
>> and commit graph phrases to the glossary of terms. While these
>> techniques are well known to their developers, for some, they are
>> just magic phrases.
> Thanks, the updated round looks good to me. I applied these on top of
> the tip of master instead of the existing merge base (which was
> dc8c8deaa6b (Prepare for 2.36.2, 2022-06-07)).
>
> Will queue.
>
> Thanks,
> Taylor
Thanks!
Philip