git-commit-graph

Write a commit-graph file for the packed commits in the repository's local .git directory

$ git commit-graph write

$ git show-ref [[-s|--hash]] | git commit-graph write --stdin-commits

$ git rev-parse [HEAD] | git commit-graph write --stdin-commits --append

git commit-graph verify [options]
git commit-graph write [options] [rev-list options]
git commit-graph read-config

--object-dir=path
    Specify the Git object directory where graph files are located or should be written.

--split=commit-id
    For 'write', create a new split commit-graph file starting from the specified commit ID.

--split-write-info
    For 'write', write information about split commit-graphs to the info file.

--split-merge=commit-id
    For 'write', merge the current split commit-graph with existing graphs, considering commits from the specified ID.

--reachable-from=commit-id
    For 'write', only include commits reachable from the specified commit ID in the graph.

--stdin-commits
    For 'write', read the list of commits to include in the graph from standard input.

--progress
    Show progress during the commit-graph operation.

--k=number
    For 'write' with splitting, specifies the number of commits to include in the base graph.

--max-graph-size=number
    For 'write' with splitting, specifies the maximum size of a split commit-graph.

--changed-paths
    For 'verify', check for changed paths recorded in the commit-graph.

--shallow
    For 'verify', perform a shallow verification, avoiding full history traversal.

--file=path
    Specify the path to the commit-graph file to operate on for 'verify' or 'read-config'.

--no-lookup-objects
    For 'verify', skip lookup of objects in the object database for validation, relying only on graph data.

The git-commit-graph command is a plumbing command used to manage commit-graph files. These files store reachability information for commits in a highly optimized format, significantly speeding up operations like git log, git rev-list, and other commands that traverse the commit history. By pre-calculating and storing parent-child relationships and reachability, Git can avoid recomputing this information on the fly, leading to faster history traversals, especially in large repositories. It can operate on a single commit-graph file or manage a chain of multiple files, which is useful for repositories with frequently changing histories or when incrementally building the graph.

git-commit-graph was introduced in Git 2.19. Older Git versions will not recognize or utilize commit-graph files. While these files significantly speed up read operations, writing them can be resource-intensive, especially for very large repositories without the use of split graphs. They are an optimization and not strictly necessary for basic repository functionality.

Split commit-graphs allow a repository to have multiple commit-graph files. This is particularly useful for large, active repositories where rebuilding a single massive graph frequently would be inefficient. A common pattern involves a base graph (containing older, stable history) and a split graph (containing newer, frequently changing history). This enables incremental updates, as only the smaller, more recent split graph needs to be rebuilt or appended, significantly reducing the overhead of keeping the graph optimized. git-commit-graph write with the --split and --split-merge options is used to manage these.

git-commit-graph was introduced in Git 2.19 (July 2018) as an experimental feature to improve the performance of history traversal. Prior to this, Git would dynamically compute reachability information, which could be slow for very large repositories. The initial implementation focused on basic graph writing and verification. Over subsequent versions, features like split commit-graphs were added (e.g., in Git 2.20 and 2.21) to allow for more flexible and incremental updates to the graph, making it practical for active repositories with frequent new commits. This has made Git's history commands significantly faster in scenarios where commit-graph files are present and up-to-date.

git log(1), git rev-list(1), git repack(1), git fsck(1)