summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2018-10-16 07:16:05 (GMT)
committerJunio C Hamano <gitster@pobox.com>2018-10-16 07:16:05 (GMT)
commit9a40ffd7519590b09e4ea5d27b273910de024b9e (patch)
tree340e6b989cb65412d6d8aa9117e85f333a9d78e4
parent3c8bf8cc148cf8afbd2410f4d1b767191d3b8648 (diff)
parent4c399442f781f70a00273746ca6a0de9fef9b0d3 (diff)
downloadgit-9a40ffd7519590b09e4ea5d27b273910de024b9e.zip
git-9a40ffd7519590b09e4ea5d27b273910de024b9e.tar.gz
git-9a40ffd7519590b09e4ea5d27b273910de024b9e.tar.bz2
Merge branch 'ma/commit-graph-docs'
Doc update. * ma/commit-graph-docs: Doc: refer to the "commit-graph file" with dash git-commit-graph.txt: refer to "*commit*-graph file" git-commit-graph.txt: typeset more in monospace git-commit-graph.txt: fix bullet lists
-rw-r--r--Documentation/git-commit-graph.txt31
-rw-r--r--Documentation/technical/commit-graph.txt8
2 files changed, 20 insertions, 19 deletions
diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
index dececb7..624470e 100644
--- a/Documentation/git-commit-graph.txt
+++ b/Documentation/git-commit-graph.txt
@@ -3,7 +3,7 @@ git-commit-graph(1)
NAME
----
-git-commit-graph - Write and verify Git commit graph files
+git-commit-graph - Write and verify Git commit-graph files
SYNOPSIS
@@ -17,24 +17,24 @@ SYNOPSIS
DESCRIPTION
-----------
-Manage the serialized commit graph file.
+Manage the serialized commit-graph file.
OPTIONS
-------
--object-dir::
- Use given directory for the location of packfiles and commit graph
+ Use given directory for the location of packfiles and commit-graph
file. This parameter exists to specify the location of an alternate
- that only has the objects directory, not a full .git directory. The
- commit graph file is expected to be at <dir>/info/commit-graph and
- the packfiles are expected to be in <dir>/pack.
+ that only has the objects directory, not a full `.git` directory. The
+ commit-graph file is expected to be at `<dir>/info/commit-graph` and
+ the packfiles are expected to be in `<dir>/pack`.
COMMANDS
--------
'write'::
-Write a commit graph file based on the commits found in packfiles.
+Write a commit-graph file based on the commits found in packfiles.
+
With the `--stdin-packs` option, generate the new commit graph by
walking objects only in the specified pack-indexes. (Cannot be combined
@@ -54,8 +54,8 @@ existing commit-graph file.
'read'::
-Read a graph file given by the commit-graph file and output basic
-details about the graph file. Used for debugging purposes.
+Read the commit-graph file and output basic details about it.
+Used for debugging purposes.
'verify'::
@@ -66,27 +66,28 @@ database. Used to check for corrupted data.
EXAMPLES
--------
-* Write a commit graph file for the packed commits in your local .git folder.
+* Write a commit-graph file for the packed commits in your local `.git`
+ directory.
+
------------------------------------------------
$ git commit-graph write
------------------------------------------------
-* Write a graph file, extending the current graph file using commits
-* in <pack-index>.
+* Write a commit-graph file, extending the current commit-graph file
+ using commits in `<pack-index>`.
+
------------------------------------------------
$ echo <pack-index> | git commit-graph write --stdin-packs
------------------------------------------------
-* Write a graph file containing all reachable commits.
+* Write a commit-graph file containing all reachable commits.
+
------------------------------------------------
$ git show-ref -s | git commit-graph write --stdin-commits
------------------------------------------------
-* Write a graph file containing all commits in the current
-* commit-graph file along with those reachable from HEAD.
+* Write a commit-graph file containing all commits in the current
+ commit-graph file along with those reachable from `HEAD`.
+
------------------------------------------------
$ git rev-parse HEAD | git commit-graph write --stdin-commits --append
diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt
index 001395e..7805b09 100644
--- a/Documentation/technical/commit-graph.txt
+++ b/Documentation/technical/commit-graph.txt
@@ -15,13 +15,13 @@ There are two main costs here:
1. Decompressing and parsing commits.
2. Walking the entire graph to satisfy topological order constraints.
-The commit graph file is a supplemental data structure that accelerates
+The commit-graph file is a supplemental data structure that accelerates
commit graph walks. If a user downgrades or disables the 'core.commitGraph'
config setting, then the existing ODB is sufficient. The file is stored
as "commit-graph" either in the .git/objects/info directory or in the info
directory of an alternate.
-The commit graph file stores the commit graph structure along with some
+The commit-graph file stores the commit graph structure along with some
extra metadata to speed up graph walks. By listing commit OIDs in lexi-
cographic order, we can identify an integer position for each commit and
refer to the parents of a commit using those integer positions. We use
@@ -103,7 +103,7 @@ that of a parent.
Design Details
--------------
-- The commit graph file is stored in a file named 'commit-graph' in the
+- The commit-graph file is stored in a file named 'commit-graph' in the
.git/objects/info directory. This could be stored in the info directory
of an alternate.
@@ -139,7 +139,7 @@ Future Work
- 'log --topo-order'
- 'tag --merged'
-- A server could provide a commit graph file as part of the network protocol
+- A server could provide a commit-graph file as part of the network protocol
to avoid extra calculations by clients. This feature is only of benefit if
the user is willing to trust the file, because verifying the file is correct
is as hard as computing it from scratch.