blob: 903b16830ea22529f476f9fadbe0c7aac4b31c12 [file] [log] [blame]
Derrick Stolee4ce58ee2018-04-02 16:34:18 -04001git-commit-graph(1)
2===================
3
4NAME
5----
Martin Ågren4c399442018-09-27 21:12:22 +02006git-commit-graph - Write and verify Git commit-graph files
Derrick Stolee4ce58ee2018-04-02 16:34:18 -04007
Derrick Stoleef237c8b2018-04-02 16:34:20 -04008
9SYNOPSIS
10--------
11[verse]
Garima Singh73716122019-08-26 09:29:58 -070012'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress]
Ævar Arnfjörð Bjarmasond9054a12022-10-13 17:39:18 +020013'git commit-graph write' [--object-dir <dir>] [--append]
14 [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]
15 [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]
Jean-Noël Avila2162f9f2023-12-25 21:21:26 +000016 <split-options>
Derrick Stoleef237c8b2018-04-02 16:34:20 -040017
18
19DESCRIPTION
20-----------
21
Martin Ågren4c399442018-09-27 21:12:22 +020022Manage the serialized commit-graph file.
Derrick Stoleef237c8b2018-04-02 16:34:20 -040023
24
25OPTIONS
26-------
27--object-dir::
Martin Ågren4c399442018-09-27 21:12:22 +020028 Use given directory for the location of packfiles and commit-graph
Derrick Stoleef237c8b2018-04-02 16:34:20 -040029 file. This parameter exists to specify the location of an alternate
Martin Ågrend59a9162018-09-27 21:12:20 +020030 that only has the objects directory, not a full `.git` directory. The
Derrick Stoleec2bc6e62019-06-18 11:14:32 -070031 commit-graph file is expected to be in the `<dir>/info` directory and
Taylor Blau0bd52e22020-02-03 21:51:50 -080032 the packfiles are expected to be in `<dir>/pack`. If the directory
33 could not be made into an absolute path, or does not match any known
34 object directory, `git commit-graph ...` will exit with non-zero
35 status.
Derrick Stoleef237c8b2018-04-02 16:34:20 -040036
Garima Singh73716122019-08-26 09:29:58 -070037--[no-]progress::
38 Turn progress on/off explicitly. If neither is specified, progress is
39 shown if standard error is connected to a terminal.
Derrick Stoleef237c8b2018-04-02 16:34:20 -040040
41COMMANDS
42--------
43'write'::
44
Derrick Stolee85102ac2020-10-09 20:53:52 +000045Write a commit-graph file based on the commits found in packfiles. If
46the config option `core.commitGraph` is disabled, then this command will
47output a warning, then return success without writing a commit-graph file.
Derrick Stolee049d51a2018-04-10 08:56:06 -040048+
49With the `--stdin-packs` option, generate the new commit graph by
Derrick Stolee3d5df012018-04-10 08:56:07 -040050walking objects only in the specified pack-indexes. (Cannot be combined
Derrick Stolee59fb8772018-06-27 09:24:45 -040051with `--stdin-commits` or `--reachable`.)
Derrick Stolee3d5df012018-04-10 08:56:07 -040052+
53With the `--stdin-commits` option, generate the new commit graph by
54walking commits starting at the commits specified in stdin as a list
Taylor Blau2f00c352020-05-13 15:59:55 -060055of OIDs in hex, one OID per line. OIDs that resolve to non-commits
56(either directly, or by peeling tags) are silently ignored. OIDs that
57are malformed, or do not exist generate an error. (Cannot be combined
58with `--stdin-packs` or `--reachable`.)
Derrick Stolee59fb8772018-06-27 09:24:45 -040059+
60With the `--reachable` option, generate the new commit graph by walking
61commits starting at all refs. (Cannot be combined with `--stdin-commits`
62or `--stdin-packs`.)
Derrick Stolee7547b952018-04-10 08:56:08 -040063+
64With the `--append` option, include all commits that are present in the
65existing commit-graph file.
Derrick Stoleec2bc6e62019-06-18 11:14:32 -070066+
Garima Singhd38e07b2020-04-06 16:59:51 +000067With the `--changed-paths` option, compute and write information about the
Martin Ågren1aa7b682020-05-17 20:52:18 +020068paths changed between a commit and its first parent. This operation can
Garima Singhd38e07b2020-04-06 16:59:51 +000069take a while on large repositories. It provides significant performance gains
Derrick Stolee0087a872020-07-01 13:27:24 +000070for getting history of a directory or a file with `git log -- <path>`. If
71this option is given, future commit-graph writes will automatically assume
72that this option was intended. Use `--no-changed-paths` to stop storing this
73data.
Garima Singhd38e07b2020-04-06 16:59:51 +000074+
Taylor Blau809e0322020-09-18 09:27:27 -040075With the `--max-new-filters=<n>` option, generate at most `n` new Bloom
76filters (if `--changed-paths` is specified). If `n` is `-1`, no limit is
77enforced. Only commits present in the new layer count against this
78limit. To retroactively compute Bloom filters over earlier layers, it is
Taylor Blaud356d5d2020-09-17 22:59:57 -040079advised to use `--split=replace`. Overrides the `commitGraph.maxNewFilters`
80configuration.
Taylor Blau809e0322020-09-18 09:27:27 -040081+
Taylor Blau4f027352020-04-13 22:04:08 -060082With the `--split[=<strategy>]` option, write the commit-graph as a
83chain of multiple commit-graph files stored in
84`<dir>/info/commit-graphs`. Commit-graph layers are merged based on the
85strategy and other splitting options. The new commits not already in the
86commit-graph are added in a new "tip" file. This file is merged with the
87existing file if the following merge conditions are met:
Martin Ågrence3614c2020-05-17 20:52:19 +020088+
Taylor Blaufdbde822020-04-13 22:04:12 -060089* If `--split=no-merge` is specified, a merge is never performed, and
Taylor Blau8a6ac282020-04-13 22:04:17 -060090the remaining options are ignored. `--split=replace` overwrites the
91existing chain with a new one. A bare `--split` defers to the remaining
92options. (Note that merging a chain of commit graphs replaces the
93existing chain with a length-1 chain where the first and only
Taylor Blaufdbde822020-04-13 22:04:12 -060094incremental holds the entire graph).
Derrick Stoleec2bc6e62019-06-18 11:14:32 -070095+
96* If `--size-multiple=<X>` is not specified, let `X` equal 2. If the new
97tip file would have `N` commits and the previous tip has `M` commits and
98`X` times `N` is greater than `M`, instead merge the two files into a
99single file.
100+
101* If `--max-commits=<M>` is specified with `M` a positive integer, and the
102new tip file would have more than `M` commits, then instead merge the new
103tip with the previous tip.
104+
105Finally, if `--expire-time=<datetime>` is not specified, let `datetime`
106be the current time. After writing the split commit-graph, delete all
107unused commit-graph whose modified times are older than `datetime`.
Derrick Stoleef237c8b2018-04-02 16:34:20 -0400108
Derrick Stolee283e68c2018-06-27 09:24:32 -0400109'verify'::
110
111Read the commit-graph file and verify its contents against the object
112database. Used to check for corrupted data.
Derrick Stolee3da4b602019-06-18 11:14:32 -0700113+
114With the `--shallow` option, only check the tip commit-graph file in
115a chain of split commit-graphs.
Derrick Stolee283e68c2018-06-27 09:24:32 -0400116
Derrick Stoleef237c8b2018-04-02 16:34:20 -0400117
118EXAMPLES
119--------
120
Martin Ågren4c399442018-09-27 21:12:22 +0200121* Write a commit-graph file for the packed commits in your local `.git`
Martin Ågrend59a9162018-09-27 21:12:20 +0200122 directory.
Derrick Stoleef237c8b2018-04-02 16:34:20 -0400123+
124------------------------------------------------
125$ git commit-graph write
126------------------------------------------------
127
Martin Ågren4893d712018-09-27 21:12:21 +0200128* Write a commit-graph file, extending the current commit-graph file
129 using commits in `<pack-index>`.
Derrick Stolee049d51a2018-04-10 08:56:06 -0400130+
131------------------------------------------------
132$ echo <pack-index> | git commit-graph write --stdin-packs
133------------------------------------------------
134
Martin Ågren4893d712018-09-27 21:12:21 +0200135* Write a commit-graph file containing all reachable commits.
Derrick Stolee3d5df012018-04-10 08:56:07 -0400136+
137------------------------------------------------
138$ git show-ref -s | git commit-graph write --stdin-commits
139------------------------------------------------
140
Martin Ågren4893d712018-09-27 21:12:21 +0200141* Write a commit-graph file containing all commits in the current
Martin Ågrend59a9162018-09-27 21:12:20 +0200142 commit-graph file along with those reachable from `HEAD`.
Derrick Stolee7547b952018-04-10 08:56:08 -0400143+
144------------------------------------------------
145$ git rev-parse HEAD | git commit-graph write --stdin-commits --append
146------------------------------------------------
147
Ævar Arnfjörð Bjarmason16f6b0d2022-09-07 10:27:04 +0200148CONFIGURATION
149-------------
150
151include::includes/cmd-config-section-all.txt[]
152
153include::config/commitgraph.txt[]
154
Derrick Stoleef237c8b2018-04-02 16:34:20 -0400155
Ævar Arnfjörð Bjarmason8cbace92022-08-04 18:28:35 +0200156FILE FORMAT
157-----------
158
159see linkgit:gitformat-commit-graph[5].
160
Derrick Stolee4ce58ee2018-04-02 16:34:18 -0400161GIT
162---
163Part of the linkgit:git[1] suite