summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/CodingGuidelines26
-rw-r--r--Documentation/RelNotes/2.22.1.txt147
-rw-r--r--Documentation/RelNotes/2.23.0.txt149
-rw-r--r--Documentation/blame-options.txt19
-rw-r--r--Documentation/config/advice.txt2
-rw-r--r--Documentation/config/blame.txt16
-rw-r--r--Documentation/config/gpg.txt2
-rw-r--r--Documentation/config/log.txt3
-rw-r--r--Documentation/git-blame.txt1
-rw-r--r--Documentation/git-cherry-pick.txt4
-rw-r--r--Documentation/git-commit-graph.txt26
-rw-r--r--Documentation/git-log.txt2
-rw-r--r--Documentation/git-multi-pack-index.txt32
-rw-r--r--Documentation/git-revert.txt4
-rw-r--r--Documentation/rev-list-options.txt8
-rw-r--r--Documentation/sequencer.txt4
-rw-r--r--Documentation/technical/api-trace2.txt2
-rw-r--r--Documentation/technical/commit-graph-format.txt11
-rw-r--r--Documentation/technical/commit-graph.txt195
19 files changed, 573 insertions, 80 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 1169ff6c8e..f45db5b727 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -195,10 +195,30 @@ For C programs:
by e.g. "echo DEVELOPER=1 >>config.mak".
- We try to support a wide range of C compilers to compile Git with,
- including old ones. That means that you should not use C99
- initializers, even if a lot of compilers grok it.
+ including old ones. You should not use features from newer C
+ standard, even if your compiler groks them.
- - Variables have to be declared at the beginning of the block.
+ There are a few exceptions to this guideline:
+
+ . since early 2012 with e1327023ea, we have been using an enum
+ definition whose last element is followed by a comma. This, like
+ an array initializer that ends with a trailing comma, can be used
+ to reduce the patch noise when adding a new identifer at the end.
+
+ . since mid 2017 with cbc0f81d, we have been using designated
+ initializers for struct (e.g. "struct t v = { .val = 'a' };").
+
+ . since mid 2017 with 512f41cf, we have been using designated
+ initializers for array (e.g. "int array[10] = { [5] = 2 }").
+
+ These used to be forbidden, but we have not heard any breakage
+ report, and they are assumed to be safe.
+
+ - Variables have to be declared at the beginning of the block, before
+ the first statement (i.e. -Wdeclaration-after-statement).
+
+ - Declaring a variable in the for loop "for (int i = 0; i < 10; i++)"
+ is still not allowed in this codebase.
- NULL pointers shall be written as NULL, not as 0.
diff --git a/Documentation/RelNotes/2.22.1.txt b/Documentation/RelNotes/2.22.1.txt
new file mode 100644
index 0000000000..76dd8fb578
--- /dev/null
+++ b/Documentation/RelNotes/2.22.1.txt
@@ -0,0 +1,147 @@
+Git 2.22.1 Release Notes
+========================
+
+Fixes since v2.22
+-----------------
+
+ * A relative pathname given to "git init --template=<path> <repo>"
+ ought to be relative to the directory "git init" gets invoked in,
+ but it instead was made relative to the repository, which has been
+ corrected.
+
+ * "git worktree add" used to fail when another worktree connected to
+ the same repository was corrupt, which has been corrected.
+
+ * The ownership rule for the file descriptor to fast-import remote
+ backend was mixed up, leading to unrelated file descriptor getting
+ closed, which has been fixed.
+
+ * "git update-server-info" used to leave stale packfiles in its
+ output, which has been corrected.
+
+ * The server side support for "git fetch" used to show incorrect
+ value for the HEAD symbolic ref when the namespace feature is in
+ use, which has been corrected.
+
+ * "git am -i --resolved" segfaulted after trying to see a commit as
+ if it were a tree, which has been corrected.
+
+ * "git bundle verify" needs to see if prerequisite objects exist in
+ the receiving repository, but the command did not check if we are
+ in a repository upfront, which has been corrected.
+
+ * "git merge --squash" is designed to update the working tree and the
+ index without creating the commit, and this cannot be countermanded
+ by adding the "--commit" option; the command now refuses to work
+ when both options are given.
+
+ * The data collected by fsmonitor was not properly written back to
+ the on-disk index file, breaking t7519 tests occasionally, which
+ has been corrected.
+
+ * Update to Unicode 12.1 width table.
+
+ * The command line to invoke a "git cat-file" command from inside
+ "git p4" was not properly quoted to protect a caret and running a
+ broken command on Windows, which has been corrected.
+
+ * "git request-pull" learned to warn when the ref we ask them to pull
+ from in the local repository and in the published repository are
+ different.
+
+ * When creating a partial clone, the object filtering criteria is
+ recorded for the origin of the clone, but this incorrectly used a
+ hardcoded name "origin" to name that remote; it has been corrected
+ to honor the "--origin <name>" option.
+
+ * "git fetch" into a lazy clone forgot to fetch base objects that are
+ necessary to complete delta in a thin packfile, which has been
+ corrected.
+
+ * The filter_data used in the list-objects-filter (which manages a
+ lazily sparse clone repository) did not use the dynamic array API
+ correctly---'nr' is supposed to point at one past the last element
+ of the array in use. This has been corrected.
+
+ * The description about slashes in gitignore patterns (used to
+ indicate things like "anchored to this level only" and "only
+ matches directories") has been revamped.
+
+ * The URL decoding code has been updated to avoid going past the end
+ of the string while parsing %-<hex>-<hex> sequence.
+
+ * The list of for-each like macros used by clang-format has been
+ updated.
+
+ * "git push --atomic" that goes over the transport-helper (namely,
+ the smart http transport) failed to prevent refs to be pushed when
+ it can locally tell that one of the ref update will fail without
+ having to consult the other end, which has been corrected.
+
+ * "git clean" silently skipped a path when it cannot lstat() it; now
+ it gives a warning.
+
+ * A codepath that reads from GPG for signed object verification read
+ past the end of allocated buffer, which has been fixed.
+
+ * "git rm" to resolve a conflicted path leaked an internal message
+ "needs merge" before actually removing the path, which was
+ confusing. This has been corrected.
+
+ * The "git clone" documentation refers to command line options in its
+ description in the short form; they have been replaced with long
+ forms to make them more recognisable.
+
+ * The configuration variable rebase.rescheduleFailedExec should be
+ effective only while running an interactive rebase and should not
+ affect anything when running a non-interactive one, which was not
+ the case. This has been corrected.
+
+ * "git submodule foreach" did not protect command line options passed
+ to the command to be run in each submodule correctly, when the
+ "--recursive" option was in use.
+
+ * Use "Erase in Line" CSI sequence that is already used in the editor
+ support to clear cruft in the progress output.
+
+ * The codepath to compute delta islands used to spew progress output
+ without giving the callers any way to squelch it, which has been
+ fixed.
+
+ * The code to parse scaled numbers out of configuration files has
+ been made more robust and also easier to follow.
+
+ * An incorrect list of options was cached after command line
+ completion failed (e.g. trying to complete a command that requires
+ a repository outside one), which has been corrected.
+
+ * "git rebase --abort" used to leave refs/rewritten/ when concluding
+ "git rebase -r", which has been corrected.
+
+ * "git stash show 23" used to work, but no more after getting
+ rewritten in C; this regression has been corrected.
+
+ * "git interpret-trailers" always treated '#' as the comment
+ character, regardless of core.commentChar setting, which has been
+ corrected.
+
+ * Code clean-up to avoid signed integer overlaps during binary search.
+
+ * "git checkout -p" needs to selectively apply a patch in reverse,
+ which did not work well.
+
+ * The commit-graph file is now part of the "files that the runtime
+ may keep open file descriptors on, all of which would need to be
+ closed when done with the object store", and the file descriptor to
+ an existing commit-graph file now is closed before "gc" finalizes a
+ new instance to replace it.
+
+ * Code restructuring during 2.20 period broke fetching tags via
+ "import" based transports.
+
+ * We have been trying out a few language features outside c89; the
+ coding guidelines document did not talk about them and instead had
+ a blanket ban against them.
+
+
+Also contains various documentation updates, code clean-ups and minor fixups.
diff --git a/Documentation/RelNotes/2.23.0.txt b/Documentation/RelNotes/2.23.0.txt
index a63204ffe8..65c8c0e58c 100644
--- a/Documentation/RelNotes/2.23.0.txt
+++ b/Documentation/RelNotes/2.23.0.txt
@@ -10,6 +10,9 @@ Backward compatibility note
prerequisite patches in an unstable way, which has been updated to
compute in a way that is compatible with "git patch-id --stable".
+ * The "git log" command by default behaves as if the --mailmap option
+ was given.
+
UI, Workflows & Features
@@ -52,7 +55,7 @@ UI, Workflows & Features
* "git fetch" and "git pull" reports when a fetch results in
non-fast-forward updates to let the user notice unusual situation.
- The commands learned "--no-shown-forced-updates" option to disable
+ The commands learned "--no-show-forced-updates" option to disable
this safety feature.
* Two new commands "git switch" and "git restore" are introduced to
@@ -68,13 +71,32 @@ UI, Workflows & Features
* The conditional inclusion mechanism learned to base the choice on
the branch the HEAD currently is on.
- * "git rev-list --objects" learned with "--no-object-names" option to
+ * "git rev-list --objects" learned the "--no-object-names" option to
squelch the path to the object that is used as a grouping hint for
pack-objects.
* A new tag.gpgSign configuration variable turns "git tag -a" into
"git tag -s".
+ * "git multi-pack-index" learned expire and repack subcommands.
+
+ * "git blame" learned to "ignore" commits in the history, whose
+ effects (as well as their presence) get ignored.
+
+ * "git cherry-pick/revert" learned a new "--skip" action.
+
+ * The tips of refs from the alternate object store can be used as
+ starting point for reachability computation now.
+
+ * Extra blank lines in "git status" output have been reduced.
+
+ * The commits in a repository can be described by multiple
+ commit-graph files now, which allows the commit-graph files to be
+ updated incrementally.
+
+ * "git range-diff" output has been tweaked for easier identification
+ of which part of what file the patch shown is about.
+
Performance, Internal Implementation, Development Support etc.
@@ -82,7 +104,7 @@ Performance, Internal Implementation, Development Support etc.
no longer be used.
* Developer support to emulate unsatisfied prerequisites in tests to
- ensure that the remainer of the tests still succeeds when tests
+ ensure that the remainder of the tests still succeeds when tests
with prerequisites are skipped.
* "git update-server-info" learned not to rewrite the file with the
@@ -97,7 +119,7 @@ Performance, Internal Implementation, Development Support etc.
* Prepare use of reachability index in topological walker that works
on a range (A..B).
- * A new tutorial targetting specifically aspiring git-core
+ * A new tutorial targeting specifically aspiring git-core
developers has been added.
* Auto-detect how to tell HP-UX aCC where to use dynamically linked
@@ -114,6 +136,36 @@ Performance, Internal Implementation, Development Support etc.
* A handful of Windows build patches have been upstreamed.
+ * The code to read state files used by the sequencer machinery for
+ "git status" has been made more robust against a corrupt or stale
+ state files.
+
+ * "git for-each-ref" with multiple patterns have been optimized.
+
+ * The tree-walk API learned to pass an in-core repository
+ instance throughout more codepaths.
+
+ * When one step in multi step cherry-pick or revert is reset or
+ committed, the command line prompt script failed to notice the
+ current status, which has been improved.
+
+ * Many GIT_TEST_* environment variables control various aspects of
+ how our tests are run, but a few followed "non-empty is true, empty
+ or unset is false" while others followed the usual "there are a few
+ ways to spell true, like yes, on, etc., and also ways to spell
+ false, like no, off, etc." convention.
+
+ * Adjust the dir-iterator API and apply it to the local clone
+ optimization codepath.
+
+ * We have been trying out a few language features outside c89; the
+ coding guidelines document did not talk about them and instead had
+ a blanket ban against them.
+
+ * A test helper has been introduced to optimize preparation of test
+ repositories with many simple commits, and a handful of test
+ scripts have been updated to use it.
+
Fixes since v2.22
-----------------
@@ -122,16 +174,13 @@ Fixes since v2.22
ought to be relative to the directory "git init" gets invoked in,
but it instead was made relative to the repository, which has been
corrected.
- (merge e1df7fe43f nd/init-relative-template-fix later to maint).
* "git worktree add" used to fail when another worktree connected to
the same repository was corrupt, which has been corrected.
- (merge 105df73e71 nd/corrupt-worktrees later to maint).
* The ownership rule for the file descriptor to fast-import remote
- backend was mixed up, leading to unrelated file descriptor getting
+ backend was mixed up, leading to an unrelated file descriptor getting
closed, which has been fixed.
- (merge 3203566a71 mh/import-transport-fd-fix later to maint).
* A "merge -c" instruction during "git rebase --rebase-merges" should
give the user a chance to edit the log message, even when there is
@@ -140,82 +189,65 @@ Fixes since v2.22
corrected.
* Code cleanup and futureproof.
- (merge 31f5256c82 ds/object-info-for-prefetch-fix later to maint).
* More parameter validation.
- (merge de99eb0c24 es/grep-require-name-when-needed later to maint).
* "git update-server-info" used to leave stale packfiles in its
output, which has been corrected.
- (merge e941c48d49 ew/server-info-remove-crufts later to maint).
* The server side support for "git fetch" used to show incorrect
value for the HEAD symbolic ref when the namespace feature is in
use, which has been corrected.
- (merge 533e088250 jk/HEAD-symref-in-xfer-namespaces later to maint).
* "git am -i --resolved" segfaulted after trying to see a commit as
if it were a tree, which has been corrected.
- (merge 7663e438c5 jk/am-i-resolved-fix later to maint).
* "git bundle verify" needs to see if prerequisite objects exist in
the receiving repository, but the command did not check if we are
in a repository upfront, which has been corrected.
- (merge 3bbbe467f2 js/bundle-verify-require-object-store later to maint).
* "git merge --squash" is designed to update the working tree and the
index without creating the commit, and this cannot be countermanded
by adding the "--commit" option; the command now refuses to work
when both options are given.
- (merge 1d14d0c994 vv/merge-squash-with-explicit-commit later to maint).
* The data collected by fsmonitor was not properly written back to
the on-disk index file, breaking t7519 tests occasionally, which
has been corrected.
- (merge b5a8169752 js/fsmonitor-unflake later to maint).
* Update to Unicode 12.1 width table.
- (merge 5817f9caa3 bb/unicode-12.1-reiwa later to maint).
* The command line to invoke a "git cat-file" command from inside
"git p4" was not properly quoted to protect a caret and running a
broken command on Windows, which has been corrected.
- (merge c3f2358de3 mm/p4-unshelve-windows-fix later to maint).
* "git request-pull" learned to warn when the ref we ask them to pull
from in the local repository and in the published repository are
different.
- (merge 0454220d66 pb/request-pull-verify-remote-ref later to maint).
* When creating a partial clone, the object filtering criteria is
recorded for the origin of the clone, but this incorrectly used a
hardcoded name "origin" to name that remote; it has been corrected
to honor the "--origin <name>" option.
- (merge 1c4a9f9114 xl/record-partial-clone-origin later to maint).
* "git fetch" into a lazy clone forgot to fetch base objects that are
necessary to complete delta in a thin packfile, which has been
corrected.
- (merge 810e19322d jt/partial-clone-missing-ref-delta-base later to maint).
* The filter_data used in the list-objects-filter (which manages a
lazily sparse clone repository) did not use the dynamic array API
correctly---'nr' is supposed to point at one past the last element
of the array in use. This has been corrected.
- (merge 7140600e2e md/list-objects-filter-memfix later to maint).
* The description about slashes in gitignore patterns (used to
indicate things like "anchored to this level only" and "only
matches directories") has been revamped.
- (merge 1a58bad014 an/ignore-doc-update later to maint).
* The URL decoding code has been updated to avoid going past the end
of the string while parsing %-<hex>-<hex> sequence.
- (merge d37dc239a4 md/url-parse-harden later to maint).
* The list of for-each like macros used by clang-format has been
updated.
- (merge fc7e03aace mo/clang-format-for-each-update later to maint).
* "git branch --list" learned to show branches that are checked out
in other worktrees connected to the same repository prefixed with
@@ -225,48 +257,38 @@ Fixes since v2.22
* Code restructuring during 2.20 period broke fetching tags via
"import" based transports.
- (merge f80d922355 fc/fetch-with-import-fix later to maint).
* The commit-graph file is now part of the "files that the runtime
may keep open file descriptors on, all of which would need to be
closed when done with the object store", and the file descriptor to
an existing commit-graph file now is closed before "gc" finalizes a
new instance to replace it.
- (merge 2d511cfc0b ds/close-object-store later to maint).
* "git checkout -p" needs to selectively apply a patch in reverse,
which did not work well.
- (merge 2bd69b9024 pw/add-p-recount later to maint).
* Code clean-up to avoid signed integer wraparounds during binary search.
- (merge 568a05c5ec rs/avoid-overflow-in-midpoint-computation later to maint).
* "git interpret-trailers" always treated '#' as the comment
character, regardless of core.commentChar setting, which has been
corrected.
- (merge 29c83fc23f jk/trailers-use-config later to maint).
* "git stash show 23" used to work, but no more after getting
rewritten in C; this regression has been corrected.
- (merge 63b50c8ffe tg/stash-ref-by-index-fix later to maint).
* "git rebase --abort" used to leave refs/rewritten/ when concluding
"git rebase -r", which has been corrected.
- (merge d559f502c5 pw/rebase-abort-clean-rewritten later to maint).
* An incorrect list of options was cached after command line
completion failed (e.g. trying to complete a command that requires
a repository outside one), which has been corrected.
- (merge 69702523af nd/completion-no-cache-failure later to maint).
* The code to parse scaled numbers out of configuration files has
been made more robust and also easier to follow.
- (merge 39c575c969 rs/config-unit-parsing later to maint).
* The codepath to compute delta islands used to spew progress output
without giving the callers any way to squelch it, which has been
fixed.
- (merge bdbdf42f8a jk/delta-islands-progress-fix later to maint).
* Protocol capabilities that go over wire should never be translated,
but it was incorrectly marked for translation, which has been
@@ -275,40 +297,51 @@ Fixes since v2.22
* Use "Erase in Line" CSI sequence that is already used in the editor
support to clear cruft in the progress output.
- (merge 5b12e3123b sg/rebase-progress later to maint).
* "git submodule foreach" did not protect command line options passed
to the command to be run in each submodule correctly, when the
"--recursive" option was in use.
- (merge 30db18b148 ms/submodule-foreach-fix later to maint).
* The configuration variable rebase.rescheduleFailedExec should be
effective only while running an interactive rebase and should not
- affect anything when running an non-interactive one, which was not
+ affect anything when running a non-interactive one, which was not
the case. This has been corrected.
- (merge 906b63942a js/rebase-reschedule-applies-only-to-interactive later to maint).
* The "git clone" documentation refers to command line options in its
description in the short form; they have been replaced with long
forms to make them more recognisable.
- (merge bfc8c84ed5 qn/clone-doc-use-long-form later to maint).
+
+ * Generation of pack bitmaps are now disabled when .keep files exist,
+ as these are mutually exclusive features.
+ (merge 7328482253 ew/repack-with-bitmaps-by-default later to maint).
+
+ * "git rm" to resolve a conflicted path leaked an internal message
+ "needs merge" before actually removing the path, which was
+ confusing. This has been corrected.
+
+ * "git stash --keep-index" did not work correctly on paths that have
+ been removed, which has been fixed.
+ (merge b932f6a5e8 tg/stash-keep-index-with-removed-paths later to maint).
+
+ * Window 7 update ;-)
+
+ * A codepath that reads from GPG for signed object verification read
+ past the end of allocated buffer, which has been fixed.
+
+ * "git clean" silently skipped a path when it cannot lstat() it; now
+ it gives a warning.
+
+ * "git push --atomic" that goes over the transport-helper (namely,
+ the smart http transport) failed to prevent refs to be pushed when
+ it can locally tell that one of the ref update will fail without
+ having to consult the other end, which has been corrected.
+
+ * The internal diff machinery can be made to read out of bounds while
+ looking for --function-context line in a corner case, which has been
+ corrected.
+ (merge b777f3fd61 jk/xdiff-clamp-funcname-context-index later to maint).
* Other code cleanup, docfix, build fix, etc.
- (merge f547101b26 es/git-debugger-doc later to maint).
- (merge 7877ac3d7b js/bisect-helper-check-get-oid-return-value later to maint).
- (merge 0108f47eb3 sw/git-p4-unshelve-branched-files later to maint).
- (merge 9df8f734fd cm/send-email-document-req-modules later to maint).
- (merge afc3bf6eb1 ab/hash-object-doc later to maint).
- (merge 1fde99cfc7 po/doc-branch later to maint).
- (merge 459842e1c2 dl/config-alias-doc later to maint).
- (merge 5d137fc2c7 cb/fsmonitor-intfix later to maint).
- (merge 921d49be86 rs/copy-array later to maint).
- (merge cc8d872e69 js/t3404-typofix later to maint).
- (merge 729a9b558b cb/mkstemps-uint-type-fix later to maint).
- (merge 9dae4fe79f js/gcc-8-and-9 later to maint).
- (merge ed33bd8f30 js/t0001-case-insensitive later to maint).
- (merge dfa880e336 jw/gitweb-sample-update later to maint).
- (merge e532a90a9f sg/t5551-fetch-smart-error-is-translated later to maint).
- (merge 8d45ad8c29 jt/t5551-test-chunked later to maint).
- (merge 1a64e07d23 sg/git-C-empty-doc later to maint).
- (merge 37a2e35395 sg/ci-brew-gcc-workaround later to maint).
+ (merge fbec05c210 cc/test-oidmap later to maint).
+ (merge 7a06fb038c jk/no-system-includes-in-dot-c later to maint).
+ (merge 81ed2b405c cb/xdiff-no-system-includes-in-dot-c later to maint).
diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt
index dc41957afa..5d122db6e9 100644
--- a/Documentation/blame-options.txt
+++ b/Documentation/blame-options.txt
@@ -110,5 +110,24 @@ commit. And the default value is 40. If there are more than one
`-C` options given, the <num> argument of the last `-C` will
take effect.
+--ignore-rev <rev>::
+ Ignore changes made by the revision when assigning blame, as if the
+ change never happened. Lines that were changed or added by an ignored
+ commit will be blamed on the previous commit that changed that line or
+ nearby lines. This option may be specified multiple times to ignore
+ more than one revision. If the `blame.markIgnoredLines` config option
+ is set, then lines that were changed by an ignored commit and attributed to
+ another commit will be marked with a `?` in the blame output. If the
+ `blame.markUnblamableLines` config option is set, then those lines touched
+ by an ignored commit that we could not attribute to another revision are
+ marked with a '*'.
+
+--ignore-revs-file <file>::
+ Ignore revisions listed in `file`, which must be in the same format as an
+ `fsck.skipList`. This option may be repeated, and these files will be
+ processed after any files specified with the `blame.ignoreRevsFile` config
+ option. An empty file name, `""`, will clear the list of revs from
+ previously processed files.
+
-h::
Show help message.
diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt
index ee85c536ce..6aaa360202 100644
--- a/Documentation/config/advice.txt
+++ b/Documentation/config/advice.txt
@@ -68,6 +68,8 @@ advice.*::
resolveConflict::
Advice shown by various commands when conflicts
prevent the operation from being performed.
+ sequencerInUse::
+ Advice shown when a sequencer command is already in progress.
implicitIdentity::
Advice on how to set your identity configuration when
your information is guessed from the system username and
diff --git a/Documentation/config/blame.txt b/Documentation/config/blame.txt
index 67b5c1d1e0..9468e8599c 100644
--- a/Documentation/config/blame.txt
+++ b/Documentation/config/blame.txt
@@ -19,3 +19,19 @@ blame.showEmail::
blame.showRoot::
Do not treat root commits as boundaries in linkgit:git-blame[1].
This option defaults to false.
+
+blame.ignoreRevsFile::
+ Ignore revisions listed in the file, one unabbreviated object name per
+ line, in linkgit:git-blame[1]. Whitespace and comments beginning with
+ `#` are ignored. This option may be repeated multiple times. Empty
+ file names will reset the list of ignored revisions. This option will
+ be handled before the command line option `--ignore-revs-file`.
+
+blame.markUnblamables::
+ Mark lines that were changed by an ignored revision that we could not
+ attribute to another commit with a '*' in the output of
+ linkgit:git-blame[1].
+
+blame.markIgnoredLines::
+ Mark lines that were changed by an ignored revision that we attributed to
+ another commit with a '?' in the output of linkgit:git-blame[1].
diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt
index f999f8ea49..cce2c89245 100644
--- a/Documentation/config/gpg.txt
+++ b/Documentation/config/gpg.txt
@@ -2,7 +2,7 @@ gpg.program::
Use this custom program instead of "`gpg`" found on `$PATH` when
making or verifying a PGP signature. The program must support the
same command-line interface as GPG, namely, to verify a detached
- signature, "`gpg --verify $file - <$signature`" is run, and the
+ signature, "`gpg --verify $signature - <$file`" is run, and the
program is expected to signal a good signature by exiting with
code 0, and to generate an ASCII-armored detached signature, the
standard input of "`gpg -bsau $key`" is fed with the contents to be
diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt
index 78d9e4453a..e9e1e397f3 100644
--- a/Documentation/config/log.txt
+++ b/Documentation/config/log.txt
@@ -40,4 +40,5 @@ log.showSignature::
log.mailmap::
If true, makes linkgit:git-log[1], linkgit:git-show[1], and
- linkgit:git-whatchanged[1] assume `--use-mailmap`.
+ linkgit:git-whatchanged[1] assume `--use-mailmap`, otherwise
+ assume `--no-use-mailmap`. True by default.
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index 16323eb80e..7e81541996 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -10,6 +10,7 @@ SYNOPSIS
[verse]
'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
[-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]
+ [--ignore-rev <rev>] [--ignore-revs-file <file>]
[--progress] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>..<rev>]
[--] <file>
diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 754b16ce0c..83ce51aedf 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -10,9 +10,7 @@ SYNOPSIS
[verse]
'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff]
[-S[<keyid>]] <commit>...
-'git cherry-pick' --continue
-'git cherry-pick' --quit
-'git cherry-pick' --abort
+'git cherry-pick' (--continue | --skip | --abort | --quit)
DESCRIPTION
-----------
diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
index 624470e198..eb5e7865f0 100644
--- a/Documentation/git-commit-graph.txt
+++ b/Documentation/git-commit-graph.txt
@@ -10,7 +10,7 @@ SYNOPSIS
--------
[verse]
'git commit-graph read' [--object-dir <dir>]
-'git commit-graph verify' [--object-dir <dir>]
+'git commit-graph verify' [--object-dir <dir>] [--shallow]
'git commit-graph write' <options> [--object-dir <dir>]
@@ -26,7 +26,7 @@ OPTIONS
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
+ commit-graph file is expected to be in the `<dir>/info` directory and
the packfiles are expected to be in `<dir>/pack`.
@@ -51,6 +51,25 @@ or `--stdin-packs`.)
+
With the `--append` option, include all commits that are present in the
existing commit-graph file.
++
+With the `--split` option, write the commit-graph as a chain of multiple
+commit-graph files stored in `<dir>/info/commit-graphs`. The new commits
+not already in the commit-graph are added in a new "tip" file. This file
+is merged with the existing file if the following merge conditions are
+met:
++
+* If `--size-multiple=<X>` is not specified, let `X` equal 2. If the new
+tip file would have `N` commits and the previous tip has `M` commits and
+`X` times `N` is greater than `M`, instead merge the two files into a
+single file.
++
+* If `--max-commits=<M>` is specified with `M` a positive integer, and the
+new tip file would have more than `M` commits, then instead merge the new
+tip with the previous tip.
++
+Finally, if `--expire-time=<datetime>` is not specified, let `datetime`
+be the current time. After writing the split commit-graph, delete all
+unused commit-graph whose modified times are older than `datetime`.
'read'::
@@ -61,6 +80,9 @@ Used for debugging purposes.
Read the commit-graph file and verify its contents against the object
database. Used to check for corrupted data.
++
+With the `--shallow` option, only check the tip commit-graph file in
+a chain of split commit-graphs.
EXAMPLES
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index b02e922dc3..b406bc4c48 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -49,7 +49,7 @@ OPTIONS
Print out the ref name given on the command line by which each
commit was reached.
---use-mailmap::
+--[no-]use-mailmap::
Use mailmap file to map author and committer names and email
addresses to canonical real names and email addresses. See
linkgit:git-shortlog[1].
diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt
index f7778a2c85..233b2b7862 100644
--- a/Documentation/git-multi-pack-index.txt
+++ b/Documentation/git-multi-pack-index.txt
@@ -9,7 +9,7 @@ git-multi-pack-index - Write and verify multi-pack-indexes
SYNOPSIS
--------
[verse]
-'git multi-pack-index' [--object-dir=<dir>] <verb>
+'git multi-pack-index' [--object-dir=<dir>] <subcommand>
DESCRIPTION
-----------
@@ -23,13 +23,35 @@ OPTIONS
`<dir>/packs/multi-pack-index` for the current MIDX file, and
`<dir>/packs` for the pack-files to index.
+The following subcommands are available:
+
write::
- When given as the verb, write a new MIDX file to
- `<dir>/packs/multi-pack-index`.
+ Write a new MIDX file.
verify::
- When given as the verb, verify the contents of the MIDX file
- at `<dir>/packs/multi-pack-index`.
+ Verify the contents of the MIDX file.
+
+expire::
+ Delete the pack-files that are tracked by the MIDX file, but
+ have no objects referenced by the MIDX. Rewrite the MIDX file
+ afterward to remove all references to these pack-files.
+
+repack::
+ Create a new pack-file containing objects in small pack-files
+ referenced by the multi-pack-index. If the size given by the
+ `--batch-size=<size>` argument is zero, then create a pack
+ containing all objects referenced by the multi-pack-index. For
+ a non-zero batch size, Select the pack-files by examining packs
+ from oldest-to-newest, computing the "expected size" by counting
+ the number of objects in the pack referenced by the
+ multi-pack-index, then divide by the total number of objects in
+ the pack and multiply by the pack size. We select packs with
+ expected size below the batch size until the set of packs have
+ total expected size at least the batch size. If the total size
+ does not reach the batch size, then do nothing. If a new pack-
+ file is created, rewrite the multi-pack-index to reference the
+ new pack-file. A later run of 'git multi-pack-index expire' will
+ delete the pack-files that were part of this batch.
EXAMPLES
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index fae4d66547..9d22270757 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -9,9 +9,7 @@ SYNOPSIS
--------
[verse]
'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>...
-'git revert' --continue
-'git revert' --quit
-'git revert' --abort
+'git revert' (--continue | --skip | --abort | --quit)
DESCRIPTION
-----------
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 286fc163f1..bb1251c036 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -182,6 +182,14 @@ explicitly.
Pretend as if all objects mentioned by reflogs are listed on the
command line as `<commit>`.
+--alternate-refs::
+ Pretend as if all objects mentioned as ref tips of alternate
+ repositories were listed on the command line. An alternate
+ repository is any repository whose object directory is specified
+ in `objects/info/alternates`. The set of included objects may
+ be modified by `core.alternateRefsCommand`, etc. See
+ linkgit:git-config[1].
+
--single-worktree::
By default, all working trees will be examined by the
following options when there are more than one (see
diff --git a/Documentation/sequencer.txt b/Documentation/sequencer.txt
index 5a57c4a407..3bceb56474 100644
--- a/Documentation/sequencer.txt
+++ b/Documentation/sequencer.txt
@@ -3,6 +3,10 @@
`.git/sequencer`. Can be used to continue after resolving
conflicts in a failed cherry-pick or revert.
+--skip::
+ Skip the current commit and continue with the rest of the
+ sequence.
+
--quit::
Forget about the current operation in progress. Can be used
to clear the sequencer state after a failed cherry-pick or
diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt
index f7ffe7d599..71eb081fed 100644
--- a/Documentation/technical/api-trace2.txt
+++ b/Documentation/technical/api-trace2.txt
@@ -668,7 +668,7 @@ completed.)
"event":"signal",
...
"t_abs":0.001227, # elapsed time in seconds
- "signal":13 # SIGTERM, SIGINT, etc.
+ "signo":13 # SIGTERM, SIGINT, etc.
}
------------
diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/technical/commit-graph-format.txt
index 16452a0504..a4f17441ae 100644
--- a/Documentation/technical/commit-graph-format.txt
+++ b/Documentation/technical/commit-graph-format.txt
@@ -44,8 +44,9 @@ HEADER:
1-byte number (C) of "chunks"
- 1-byte (reserved for later use)
- Current clients should ignore this value.
+ 1-byte number (B) of base commit-graphs
+ We infer the length (H*B) of the Base Graphs chunk
+ from this value.
CHUNK LOOKUP:
@@ -92,6 +93,12 @@ CHUNK DATA:
positions for the parents until reaching a value with the most-significant
bit on. The other bits correspond to the position of the last parent.
+ Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]
+ This list of H-byte hashes describe a set of B commit-graph files that
+ form a commit-graph chain. The graph position for the ith commit in this
+ file's OID Lookup chunk is equal to i plus the number of commits in all
+ base graphs. If B is non-zero, this chunk must exist.
+
TRAILER:
H-byte HASH-checksum of all of the above.
diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt
index fb53341d5e..729fbcb32f 100644
--- a/Documentation/technical/commit-graph.txt
+++ b/Documentation/technical/commit-graph.txt
@@ -127,6 +127,197 @@ Design Details
helpful for these clones, anyway. The commit-graph will not be read or
written when shallow commits are present.
+Commit Graphs Chains
+--------------------
+
+Typically, repos grow with near-constant velocity (commits per day). Over time,
+the number of commits added by a fetch operation is much smaller than the
+number of commits in the full history. By creating a "chain" of commit-graphs,
+we enable fast writes of new commit data without rewriting the entire commit
+history -- at least, most of the time.
+
+## File Layout
+
+A commit-graph chain uses multiple files, and we use a fixed naming convention
+to organize these files. Each commit-graph file has a name
+`$OBJDIR/info/commit-graphs/graph-{hash}.graph` where `{hash}` is the hex-
+valued hash stored in the footer of that file (which is a hash of the file's
+contents before that hash). For a chain of commit-graph files, a plain-text
+file at `$OBJDIR/info/commit-graphs/commit-graph-chain` contains the
+hashes for the files in order from "lowest" to "highest".
+
+For example, if the `commit-graph-chain` file contains the lines
+
+```
+ {hash0}
+ {hash1}
+ {hash2}
+```
+
+then the commit-graph chain looks like the following diagram:
+
+ +-----------------------+
+ | graph-{hash2}.graph |
+ +-----------------------+
+ |
+ +-----------------------+
+ | |
+ | graph-{hash1}.graph |
+ | |
+ +-----------------------+
+ |
+ +-----------------------+
+ | |
+ | |
+ | |
+ | graph-{hash0}.graph |
+ | |
+ | |
+ | |
+ +-----------------------+
+
+Let X0 be the number of commits in `graph-{hash0}.graph`, X1 be the number of
+commits in `graph-{hash1}.graph`, and X2 be the number of commits in
+`graph-{hash2}.graph`. If a commit appears in position i in `graph-{hash2}.graph`,
+then we interpret this as being the commit in position (X0 + X1 + i), and that
+will be used as its "graph position". The commits in `graph-{hash2}.graph` use these
+positions to refer to their parents, which may be in `graph-{hash1}.graph` or
+`graph-{hash0}.graph`. We can navigate to an arbitrary commit in position j by checking
+its containment in the intervals [0, X0), [X0, X0 + X1), [X0 + X1, X0 + X1 +
+X2).
+
+Each commit-graph file (except the base, `graph-{hash0}.graph`) contains data
+specifying the hashes of all files in the lower layers. In the above example,
+`graph-{hash1}.graph` contains `{hash0}` while `graph-{hash2}.graph` contains
+`{hash0}` and `{hash1}`.
+
+## Merging commit-graph files
+
+If we only added a new commit-graph file on every write, we would run into a
+linear search problem through many commit-graph files. Instead, we use a merge
+strategy to decide when the stack should collapse some number of levels.
+
+The diagram below shows such a collapse. As a set of new commits are added, it
+is determined by the merge strategy that the files should collapse to
+`graph-{hash1}`. Thus, the new commits, the commits in `graph-{hash2}` and
+the commits in `graph-{hash1}` should be combined into a new `graph-{hash3}`
+file.
+
+ +---------------------+
+ | |
+ | (new commits) |
+ | |
+ +---------------------+
+ | |
+ +-----------------------+ +---------------------+
+ | graph-{hash2} |->| |
+ +-----------------------+ +---------------------+
+ | | |
+ +-----------------------+ +---------------------+
+ | | | |
+ | graph-{hash1} |->| |
+ | | | |
+ +-----------------------+ +---------------------+
+ | tmp_graphXXX
+ +-----------------------+
+ | |
+ | |
+ | |
+ | graph-{hash0} |
+ | |
+ | |
+ | |
+ +-----------------------+
+
+During this process, the commits to write are combined, sorted and we write the
+contents to a temporary file, all while holding a `commit-graph-chain.lock`
+lock-file. When the file is flushed, we rename it to `graph-{hash3}`
+according to the computed `{hash3}`. Finally, we write the new chain data to
+`commit-graph-chain.lock`:
+
+```
+ {hash3}
+ {hash0}
+```
+
+We then close the lock-file.
+
+## Merge Strategy
+
+When writing a set of commits that do not exist in the commit-graph stack of
+height N, we default to creating a new file at level N + 1. We then decide to
+merge with the Nth level if one of two conditions hold:
+
+ 1. `--size-multiple=<X>` is specified or X = 2, and the number of commits in
+ level N is less than X times the number of commits in level N + 1.
+
+ 2. `--max-commits=<C>` is specified with non-zero C and the number of commits
+ in level N + 1 is more than C commits.
+
+This decision cascades down the levels: when we merge a level we create a new
+set of commits that then compares to the next level.
+
+The first condition bounds the number of levels to be logarithmic in the total
+number of commits. The second condition bounds the total number of commits in
+a `graph-{hashN}` file and not in the `commit-graph` file, preventing
+significant performance issues when the stack merges and another process only
+partially reads the previous stack.
+
+The merge strategy values (2 for the size multiple, 64,000 for the maximum
+number of commits) could be extracted into config settings for full
+flexibility.
+
+## Deleting graph-{hash} files
+
+After a new tip file is written, some `graph-{hash}` files may no longer
+be part of a chain. It is important to remove these files from disk, eventually.
+The main reason to delay removal is that another process could read the
+`commit-graph-chain` file before it is rewritten, but then look for the
+`graph-{hash}` files after they are deleted.
+
+To allow holding old split commit-graphs for a while after they are unreferenced,
+we update the modified times of the files when they become unreferenced. Then,
+we scan the `$OBJDIR/info/commit-graphs/` directory for `graph-{hash}`
+files whose modified times are older than a given expiry window. This window
+defaults to zero, but can be changed using command-line arguments or a config
+setting.
+
+## Chains across multiple object directories
+
+In a repo with alternates, we look for the `commit-graph-chain` file starting
+in the local object directory and then in each alternate. The first file that
+exists defines our chain. As we look for the `graph-{hash}` files for
+each `{hash}` in the chain file, we follow the same pattern for the host
+directories.
+
+This allows commit-graphs to be split across multiple forks in a fork network.
+The typical case is a large "base" repo with many smaller forks.
+
+As the base repo advances, it will likely update and merge its commit-graph
+chain more frequently than the forks. If a fork updates their commit-graph after
+the base repo, then it should "reparent" the commit-graph chain onto the new
+chain in the base repo. When reading each `graph-{hash}` file, we track
+the object directory containing it. During a write of a new commit-graph file,
+we check for any changes in the source object directory and read the
+`commit-graph-chain` file for that source and create a new file based on those
+files. During this "reparent" operation, we necessarily need to collapse all
+levels in the fork, as all of the files are invalid against the new base file.
+
+It is crucial to be careful when cleaning up "unreferenced" `graph-{hash}.graph`
+files in this scenario. It falls to the user to define the proper settings for
+their custom environment:
+
+ 1. When merging levels in the base repo, the unreferenced files may still be
+ referenced by chains from fork repos.
+
+ 2. The expiry time should be set to a length of time such that every fork has
+ time to recompute their commit-graph chain to "reparent" onto the new base
+ file(s).
+
+ 3. If the commit-graph chain is updated in the base, the fork will not have
+ access to the new chain until its chain is updated to reference those files.
+ (This may change in the future [5].)
+
Related Links
-------------
[0] https://bugs.chromium.org/p/git/issues/detail?id=8
@@ -153,3 +344,7 @@ Related Links
[4] https://public-inbox.org/git/20180108154822.54829-1-git@jeffhostetler.com/T/#u
A patch to remove the ahead-behind calculation from 'status'.
+
+[5] https://public-inbox.org/git/f27db281-abad-5043-6d71-cbb083b1c877@gmail.com/
+ A discussion of a "two-dimensional graph position" that can allow reading
+ multiple commit-graph chains at the same time.
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-11 03:24:31 +0000