diff options
Diffstat (limited to 'Documentation')
32 files changed, 742 insertions, 386 deletions
diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc index bdfad29d8a..61bdd586b9 100644 --- a/Documentation/BreakingChanges.adoc +++ b/Documentation/BreakingChanges.adoc @@ -178,6 +178,12 @@ references. + These features will be removed. +* Support for "--stdin" option in the "name-rev" command was + deprecated (and hidden from the documentation) in the Git 2.40 + timeframe, in preference to its synonym "--annotate-stdin". Git 3.0 + removes the support for "--stdin" altogether. + + == Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index a0e7041c54..c1046abfb7 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -861,6 +861,9 @@ Markup: _<git-dir>_ _<key-id>_ +Characters are also surrounded by underscores: + _LF_, _CR_, _CR_/_LF_, _NUL_, _EOF_ + Git's Asciidoc processor has been tailored to treat backticked text as complex synopsis. When literal and placeholders are mixed, you can use the backtick notation which will take care of correctly typesetting diff --git a/Documentation/Makefile b/Documentation/Makefile index e6b20c021f..0d3a2c6bfe 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -109,6 +109,7 @@ SP_ARTICLES += howto/coordinate-embargoed-releases API_DOCS = $(patsubst %.adoc,%,$(filter-out technical/api-index-skel.adoc technical/api-index.adoc, $(wildcard technical/api-*.adoc))) SP_ARTICLES += $(API_DOCS) +TECH_DOCS += BreakingChanges TECH_DOCS += DecisionMaking TECH_DOCS += ReviewingGuidelines TECH_DOCS += MyFirstContribution diff --git a/Documentation/RelNotes/2.50.0.adoc b/Documentation/RelNotes/2.50.0.adoc index 1905c61e9e..e4b731e61d 100644 --- a/Documentation/RelNotes/2.50.0.adoc +++ b/Documentation/RelNotes/2.50.0.adoc @@ -7,6 +7,50 @@ UI, Workflows & Features * A post-processing filter for "diff --raw" output has been introduced. + * "git repack" learned "--combine-cruft-below-size" option that + controls how cruft-packs are combined. + + * TCP keepalive behaviour on http transports can now be configured by + calling cURL library. + + * Incrementally updating multi-pack index files. + + * "git reflog" learns "drop" subcommand, that discards the entire + reflog data for a ref. + + * A new userdiff driver for ".ini" format configuration files has + been added. + + * The job to coalesce loose objects into packfiles in "git + maintenance" now has configurable batch size. + + * "git clone" still gave the message about the default branch name; + this message has been turned into an advice message that can be + turned off. + + * "git rev-list" learns machine-parsable output format that delimits + each field with NUL. + + * "git maintenance" learns a new task to expire reflog entries. + + * Auth-related (and unrelated) error handling in send-email has been + made more robust. + + * Updating multiple references have only been possible in all-or-none + fashion with transactions, but it can be more efficient to batch + multiple updates even when some of them are allowed to fail in a + best-effort manner. A new "best effort batches of updates" mode + has been introduced. + + * "git help --build-options" reports SHA-1 and SHA-256 backends used + in the build. + + * "git cat-file --batch" and friends learned to allow "--filter=" to + omit certain objects, just like the transport layer does. + + * "git blame --porcelain" mode now talks about unblamable lines and + lines that are blamed to an ignored commit. + Performance, Internal Implementation, Development Support etc. -------------------------------------------------------------- @@ -34,8 +78,39 @@ Performance, Internal Implementation, Development Support etc. * Enable -Wunreachable-code for developer builds. - * Build update. - (merge 7c8cd9c158 es/meson-building-docs-requires-perl later to maint). + * Ensure what we write in assert() does not have side effects, + and introduce ASSERT() macro to mark those that cannot be + mechanically checked for lack of side effects. + + * Give more meaningful error return values from block writer layer of + the reftable ref-API backend. + + * Make the code in reftable library less reliant on the service + routines it used to borrow from Git proper, to make it easier to + use by external users of the library. + + * CI update. + + * The object layer has been updated to take an explicit repository + instance as a parameter in more code paths. + + * Some warnings from "-Wsign-compare" for builtin/rm.c have been + squelched. + + * A few traditional unit tests have been rewritten to use the clar + framework. + + * Some warnings from "-Wsign-compare" for pathspec.c have been + squelched. + + * "make test" used to have a hard dependency on (basic) Perl; tests + have been rewritten help environment with NO_PERL test the build as + much as possible. + + * Remove remnants of the recursive merge strategy backend, which was + superseded by the ort merge strategy. + + * Optimize the code to dedup references recorded in a bundle file. Fixes since v2.49 @@ -59,6 +134,82 @@ Fixes since v2.49 context size is given, which has been corrected. (merge d39e28e68c rs/xdiff-context-length-fix later to maint). + * GitHub Actions CI switched on a CI/CD variable that does not exist + when choosing what packages to install etc., which has been + corrected. + (merge ee89f7c79d kn/ci-meson-check-build-docs-fix later to maint). + + * Using "git name-rev --stdin" as an example, improve the framework to + prepare tests to pretend to be in the future where the breaking + changes have already happened. + (merge de3dec1187 jc/name-rev-stdin later to maint). + + * An earlier code refactoring of the hash machinery missed a few + required calls to init_fn. + (merge d39f04b638 jh/hash-init-fixes later to maint). + + * A documentation page was left out from formatting and installation, + which has been corrected. + (merge ae85116f18 pw/build-breaking-changes-doc later to maint). + + * The bash command line completion script (in contrib/) has been + updated to cope with remote repository nicknames with slashes in + them. + (merge 778d2f1760 dm/completion-remote-names-fix later to maint). + + * "Dubious ownership" checks on Windows has been tightened up. + (merge 5bb88e89ef js/mingw-admins-are-special later to maint). + + * Layout configuration in vimdiff backend didn't work as advertised, + which has been corrected. + (merge 93bab2d04b fr/vimdiff-layout-fixes later to maint). + + * Fix our use of zlib corner cases. + (merge 1cb2f293f5 jk/zlib-inflate-fixes later to maint). + + * Fix lockfile contention in reftable code on Windows. + (merge 0a3dceabf1 ps/mingw-creat-excl-fix later to maint). + + * "git-merge-file" documentation source, which has lines that look + like conflict markers, lacked custom conflict marker size defined, + which has been corrected.. + (merge d3b5832381 pw/custom-conflict-marker-size-for-merge-related-docs later to maint). + + * Squelch false-positive from sparse. + (merge da87b58014 dd/sparse-glibc-workaround later to maint). + + * Adjust to the deprecation of use of Ubuntu 20.04 GitHub Actions CI. + (merge 832d9f6d0b js/ci-github-update-ubuntu later to maint). + + * Work around CI breakage due to fedora base image getting updated. + (merge 8a471a663b js/ci-fedora-gawk later to maint). + + * A ref transaction corner case fix. + (merge b9fadeead7 jt/ref-transaction-abort-fix later to maint). + + * Random build fixes. + (merge 85e1d6819f ps/misc-build-fixes later to maint). + + * "git fetch [<remote>]" with only the configured fetch refspec + should be the only thing to update refs/remotes/<remote>/HEAD, + but the code was overly eager to do so in other cases. + + * Incorrect sorting of refs with bytes with high-bit set on platforms + with signed char led to a BUG, which has been corrected. + + * "make perf" fixes. + (merge 1665f12fa0 pb/perf-test-fixes later to maint). + + * Doc mark-up updates. + (merge 5a5565ec44 ja/doc-reset-mv-rm-markup-updates later to maint). + + * Work around false positive from CodeQL checker. + (merge 0f558141ed js/range-check-codeql-workaround later to maint). + + * "git log --{left,right}-only A...B", when A and B does not share + any common ancestor, now behaves as expected. + (merge e7ef4be7c2 mh/left-right-limited later to maint). + * Other code cleanup, docfix, build fix, etc. (merge 227c4f33a0 ja/doc-block-delimiter-markup-fix later to maint). (merge 2bfd3b3685 ab/decorate-code-cleanup later to maint). @@ -66,3 +217,16 @@ Fixes since v2.49 (merge 554051d691 en/diff-rename-follow-fix later to maint). (merge a18c18b470 en/random-cleanups later to maint). (merge 5af21c9acb hj/doc-rev-list-ancestry-fix later to maint). + (merge 26d76ca284 aj/doc-restore-p-update later to maint). + (merge 2c0dcb9754 cc/lop-remote later to maint). + (merge 7b399322a2 ja/doc-branch-markup later to maint). + (merge ee434e1807 pw/doc-pack-refs-markup-fix later to maint). + (merge c000918eb7 tb/bitamp-typofix later to maint). + (merge fa8cd29676 js/imap-send-peer-cert-verify later to maint). + (merge 98b423bc1c rs/clear-commit-marks-simplify later to maint). + (merge 133d065dd6 ta/bulk-checkin-signed-compare-false-warning-fix later to maint). + (merge d2827dc31e es/meson-build-skip-coccinelle later to maint). + (merge ee8edb7156 dk/vimdiff-doc-fix later to maint). + (merge 107d889303 md/t1403-path-is-file later to maint). + (merge abd4192b07 js/comma-semicolon-confusion later to maint). + (merge 27b7264206 ab/environment-clean-header later to maint). diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in index f2aef6cb79..9d9139306e 100644 --- a/Documentation/asciidoc.conf.in +++ b/Documentation/asciidoc.conf.in @@ -43,7 +43,7 @@ ifdef::doctype-book[] endif::doctype-book[] [literal-inlinemacro] -{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))} +{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@\\\*\/_^\$]+\.?)+|,)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))} endif::backend-docbook[] @@ -75,18 +75,18 @@ git-relative-html-prefix= <a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a> [literal-inlinemacro] -{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))} +{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\\\*\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))} endif::backend-xhtml11[] ifdef::backend-docbook[] ifdef::doctype-manpage[] [paradef-default] -synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|…\\)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]\\+>!<emphasis>\\0</emphasis>!g'" +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]\\+>!<emphasis>\\0</emphasis>!g'" endif::doctype-manpage[] endif::backend-docbook[] ifdef::backend-xhtml11[] [paradef-default] -synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|…\\)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]\\+>!<em>\\0</em>!g'" +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]\\+>!<em>\\0</em>!g'" endif::backend-xhtml11[] diff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in index 2494f17a51..8b7b161349 100644 --- a/Documentation/asciidoctor-extensions.rb.in +++ b/Documentation/asciidoctor-extensions.rb.in @@ -49,8 +49,8 @@ module Git def process parent, reader, attrs outlines = reader.lines.map do |l| - l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2') - .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$]+)}, '\1{empty}`\2`{empty}') + l.gsub(/(\.\.\.?)([^\]$\. ])/, '{empty}`\1`{empty}\2') + .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$\\\*]+)}, '\1{empty}`\2`{empty}') .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__') .gsub(']', ']{empty}') end @@ -71,8 +71,9 @@ module Git # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>) elsif type == :monospaced - node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2') - .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>') + node.text.gsub(/(\.\.\.?)([^\]$\.])/, '<literal>\1</literal>\2') + .gsub(/^\.\.\.?$/, '<literal>\0</literal>') + .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@/_^\$\\\*]+\.{0,2})+|,)}, '\1<literal>\2</literal>') .gsub(/(<[-a-zA-Z0-9.]+>)/, '<emphasis>\1</emphasis>') else open, close, supports_phrase = QUOTE_TAGS[type] @@ -100,7 +101,8 @@ module Git def convert_inline_quoted node if node.type == :monospaced node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2') - .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>') + .gsub(/^\.\.\.?$/, '<code>\0</code>') + .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*]+\.{0,2})+)}, '\1<code>\2</code>') .gsub(/(<[-a-zA-Z0-9.]+>)/, '<em>\1</em>') else diff --git a/Documentation/blame-options.adoc b/Documentation/blame-options.adoc index aa77406d4e..19ea187238 100644 --- a/Documentation/blame-options.adoc +++ b/Documentation/blame-options.adoc @@ -125,7 +125,8 @@ take effect. 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 '*'. + marked with a '*'. In the porcelain modes, we print 'ignored' and + 'unblamable' on a newline respectively. --ignore-revs-file <file>:: Ignore revisions listed in `file`, which must be in the same format as an diff --git a/Documentation/config/branch.adoc b/Documentation/config/branch.adoc index 432b9cd2c0..e35ea7ac64 100644 --- a/Documentation/config/branch.adoc +++ b/Documentation/config/branch.adoc @@ -1,41 +1,42 @@ -branch.autoSetupMerge:: - Tells 'git branch', 'git switch' and 'git checkout' to set up new branches +`branch.autoSetupMerge`:: + Tells `git branch`, `git switch` and `git checkout` to set up new branches so that linkgit:git-pull[1] will appropriately merge from the starting point branch. Note that even if this option is not set, this behavior can be chosen per-branch using the `--track` - and `--no-track` options. The valid settings are: `false` -- no - automatic setup is done; `true` -- automatic setup is done when the - starting point is a remote-tracking branch; `always` -- - automatic setup is done when the starting point is either a - local branch or remote-tracking branch; `inherit` -- if the starting point - has a tracking configuration, it is copied to the new - branch; `simple` -- automatic setup is done only when the starting point + and `--no-track` options. This option defaults to `true`. The valid settings + are: +`false`;; no automatic setup is done +`true`;; automatic setup is done when the starting point is a remote-tracking branch +`always`;; automatic setup is done when the starting point is either a + local branch or remote-tracking branch +`inherit`;; if the starting point has a tracking configuration, it is copied to the new + branch +`simple`;; automatic setup is done only when the starting point is a remote-tracking branch and the new branch has the same name as the - remote branch. This option defaults to true. + remote branch. -branch.autoSetupRebase:: - When a new branch is created with 'git branch', 'git switch' or 'git checkout' +`branch.autoSetupRebase`:: + When a new branch is created with `git branch`, `git switch` or `git checkout` that tracks another branch, this variable tells Git to set - up pull to rebase instead of merge (see "branch.<name>.rebase"). - When `never`, rebase is never automatically set to true. - When `local`, rebase is set to true for tracked branches of - other local branches. - When `remote`, rebase is set to true for tracked branches of - remote-tracking branches. - When `always`, rebase will be set to true for all tracking - branches. - See "branch.autoSetupMerge" for details on how to set up a - branch to track another branch. - This option defaults to never. + up pull to rebase instead of merge (see `branch.<name>.rebase`). + The valid settings are: +`never`;; rebase is never automatically set to true. +`local`;; rebase is set to true for tracked branches of other local branches. +`remote`;; rebase is set to true for tracked branches of remote-tracking branches. +`always`;; rebase will be set to true for all tracking branches. -branch.sort:: ++ +See `branch.autoSetupMerge` for details on how to set up a branch to track another branch. +This option defaults to `never`. + +`branch.sort`:: This variable controls the sort ordering of branches when displayed by - linkgit:git-branch[1]. Without the "--sort=<value>" option provided, the + linkgit:git-branch[1]. Without the `--sort=<value>` option provided, the value of this variable will be used as the default. See linkgit:git-for-each-ref[1] field names for valid values. -branch.<name>.remote:: - When on branch <name>, it tells 'git fetch' and 'git push' +`branch.<name>.remote`:: + When on branch _<name>_, it tells `git fetch` and `git push` which remote to fetch from or push to. The remote to push to may be overridden with `remote.pushDefault` (for all branches). The remote to push to, for the current branch, may be further @@ -46,58 +47,58 @@ branch.<name>.remote:: Additionally, `.` (a period) is the current local repository (a dot-repository), see `branch.<name>.merge`'s final note below. -branch.<name>.pushRemote:: - When on branch <name>, it overrides `branch.<name>.remote` for +`branch.<name>.pushRemote`:: + When on branch _<name>_, it overrides `branch.<name>.remote` for pushing. It also overrides `remote.pushDefault` for pushing - from branch <name>. When you pull from one place (e.g. your + from branch _<name>_. When you pull from one place (e.g. your upstream) and push to another place (e.g. your own publishing repository), you would want to set `remote.pushDefault` to specify the remote to push to for all branches, and use this option to override it for a specific branch. -branch.<name>.merge:: - Defines, together with branch.<name>.remote, the upstream branch - for the given branch. It tells 'git fetch'/'git pull'/'git rebase' which - branch to merge and can also affect 'git push' (see push.default). - When in branch <name>, it tells 'git fetch' the default - refspec to be marked for merging in FETCH_HEAD. The value is +`branch.<name>.merge`:: + Defines, together with `branch.<name>.remote`, the upstream branch + for the given branch. It tells `git fetch`/`git pull`/`git rebase` which + branch to merge and can also affect `git push` (see `push.default`). + When in branch _<name>_, it tells `git fetch` the default + refspec to be marked for merging in `FETCH_HEAD`. The value is handled like the remote part of a refspec, and must match a ref which is fetched from the remote given by - "branch.<name>.remote". - The merge information is used by 'git pull' (which first calls - 'git fetch') to lookup the default branch for merging. Without - this option, 'git pull' defaults to merge the first refspec fetched. + `branch.<name>.remote`. + The merge information is used by `git pull` (which first calls + `git fetch`) to lookup the default branch for merging. Without + this option, `git pull` defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. - If you wish to setup 'git pull' so that it merges into <name> from + If you wish to setup `git pull` so that it merges into <name> from another branch in the local repository, you can point branch.<name>.merge to the desired branch, and use the relative path - setting `.` (a period) for branch.<name>.remote. + setting `.` (a period) for `branch.<name>.remote`. -branch.<name>.mergeOptions:: - Sets default options for merging into branch <name>. The syntax and +`branch.<name>.mergeOptions`:: + Sets default options for merging into branch _<name>_. The syntax and supported options are the same as those of linkgit:git-merge[1], but option values containing whitespace characters are currently not supported. -branch.<name>.rebase:: - When true, rebase the branch <name> on top of the fetched branch, +`branch.<name>.rebase`:: + When true, rebase the branch _<name>_ on top of the fetched branch, instead of merging the default branch from the default remote when - "git pull" is run. See "pull.rebase" for doing this in a non + `git pull` is run. See `pull.rebase` for doing this in a non branch-specific manner. + -When `merges` (or just 'm'), pass the `--rebase-merges` option to 'git rebase' +When `merges` (or just `m`), pass the `--rebase-merges` option to `git rebase` so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When the value is `interactive` (or just 'i'), the rebase is run in interactive +When the value is `interactive` (or just `i`), the rebase is run in interactive mode. + *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand the implications (see linkgit:git-rebase[1] for details). -branch.<name>.description:: +`branch.<name>.description`:: Branch description, can be edited with `git branch --edit-description`. Branch description is - automatically added to the format-patch cover letter or - request-pull summary. + automatically added to the `format-patch` cover letter or + `request-pull` summary. diff --git a/Documentation/config/core.adoc b/Documentation/config/core.adoc index 8f6d8e7754..9fde1ab63a 100644 --- a/Documentation/config/core.adoc +++ b/Documentation/config/core.adoc @@ -512,6 +512,11 @@ centrally configure your Git hooks instead of configuring them on a per-repository basis, or as a more flexible and centralized alternative to having an `init.templateDir` where you've changed default hooks. ++ +You can also disable all hooks entirely by setting `core.hooksPath` +to `/dev/null`. This is usually only advisable for expert users and +on a per-command basis using configuration parameters of the form +`git -c core.hooksPath=/dev/null ...`. core.editor:: Commands such as `commit` and `tag` that let you edit diff --git a/Documentation/config/http.adoc b/Documentation/config/http.adoc index 22a8803dea..67393282fa 100644 --- a/Documentation/config/http.adoc +++ b/Documentation/config/http.adoc @@ -296,6 +296,24 @@ http.lowSpeedLimit, http.lowSpeedTime:: Can be overridden by the `GIT_HTTP_LOW_SPEED_LIMIT` and `GIT_HTTP_LOW_SPEED_TIME` environment variables. +http.keepAliveIdle:: + Specifies how long in seconds to wait on an idle connection + before sending TCP keepalive probes (if supported by the OS). If + unset, curl's default value is used. Can be overridden by the + `GIT_HTTP_KEEPALIVE_IDLE` environment variable. + +http.keepAliveInterval:: + Specifies how long in seconds to wait between TCP keepalive + probes (if supported by the OS). If unset, curl's default value + is used. Can be overridden by the `GIT_HTTP_KEEPALIVE_INTERVAL` + environment variable. + +http.keepAliveCount:: + Specifies how many TCP keepalive probes to send before giving up + and terminating the connection (if supported by the OS). If + unset, curl's default value is used. Can be overridden by the + `GIT_HTTP_KEEPALIVE_COUNT` environment variable. + http.noEPSV:: A boolean which disables using of EPSV ftp command by curl. This can be helpful with some "poor" ftp servers which don't diff --git a/Documentation/config/maintenance.adoc b/Documentation/config/maintenance.adoc index 72a9d6cf81..41536162a7 100644 --- a/Documentation/config/maintenance.adoc +++ b/Documentation/config/maintenance.adoc @@ -61,6 +61,11 @@ maintenance.loose-objects.auto:: loose objects is at least the value of `maintenance.loose-objects.auto`. The default value is 100. +maintenance.loose-objects.batchSize:: + This integer config option controls the maximum number of loose objects + written into a packfile during the `loose-objects` task. The default is + fifty thousand. Use value `0` to indicate no limit. + maintenance.incremental-repack.auto:: This integer config option controls how often the `incremental-repack` task should be run as part of `git maintenance run --auto`. If zero, @@ -69,3 +74,12 @@ maintenance.incremental-repack.auto:: Otherwise, a positive value implies the command should run when the number of pack-files not in the multi-pack-index is at least the value of `maintenance.incremental-repack.auto`. The default value is 10. + +maintenance.reflog-expire.auto:: + This integer config option controls how often the `reflog-expire` task + should be run as part of `git maintenance run --auto`. If zero, then + the `reflog-expire` task will not run with the `--auto` option. A + negative value will force the task to run every time. Otherwise, a + positive value implies the command should run when the number of + expired reflog entries in the "HEAD" reflog is at least the value of + `maintenance.loose-objects.auto`. The default value is 100. diff --git a/Documentation/config/promisor.adoc b/Documentation/config/promisor.adoc index 9192acfd24..2638b01f83 100644 --- a/Documentation/config/promisor.adoc +++ b/Documentation/config/promisor.adoc @@ -26,5 +26,5 @@ promisor.acceptFromServer:: server will be accepted. By accepting a promisor remote, the client agrees that the server might omit objects that are lazily fetchable from this promisor remote from its responses - to "fetch" and "clone" requests from the client. See - linkgit:gitprotocol-v2[5]. + to "fetch" and "clone" requests from the client. Name and URL + comparisons are case sensitive. See linkgit:gitprotocol-v2[5]. diff --git a/Documentation/config/remote.adoc b/Documentation/config/remote.adoc index 25fe219d10..91e46f66f5 100644 --- a/Documentation/config/remote.adoc +++ b/Documentation/config/remote.adoc @@ -108,7 +108,8 @@ the values inherited from a lower priority configuration files (e.g. `$HOME/.gitconfig`). remote.<name>.followRemoteHEAD:: - How linkgit:git-fetch[1] should handle updates to `remotes/<name>/HEAD`. + How linkgit:git-fetch[1] should handle updates to `remotes/<name>/HEAD` + when fetching using the configured refspecs of a remote. The default value is "create", which will create `remotes/<name>/HEAD` if it exists on the remote, but not locally; this will not touch an already existing local reference. Setting it to "warn" will print diff --git a/Documentation/git-blame.adoc b/Documentation/git-blame.adoc index f75ed44790..e438d28625 100644 --- a/Documentation/git-blame.adoc +++ b/Documentation/git-blame.adoc @@ -135,10 +135,11 @@ header elements later. The porcelain format generally suppresses commit information that has already been seen. For example, two lines that are blamed to the same commit will both be shown, but the details for that commit will be shown -only once. This is more efficient, but may require more state be kept by -the reader. The `--line-porcelain` option can be used to output full -commit information for each line, allowing simpler (but less efficient) -usage like: +only once. Information which is specific to individual lines will not be +grouped together, like revs to be marked 'ignored' or 'unblamable'. This +is more efficient, but may require more state be kept by the reader. The +`--line-porcelain` option can be used to output full commit information +for each line, allowing simpler (but less efficient) usage like: # count the number of lines attributed to each author git blame --line-porcelain file | diff --git a/Documentation/git-branch.adoc b/Documentation/git-branch.adoc index 7a073a36d6..50a1e13e1f 100644 --- a/Documentation/git-branch.adoc +++ b/Documentation/git-branch.adoc @@ -7,23 +7,23 @@ git-branch - List, create, or delete branches SYNOPSIS -------- -[verse] -'git branch' [--color[=<when>] | --no-color] [--show-current] - [-v [--abbrev=<n> | --no-abbrev]] - [--column[=<options>] | --no-column] [--sort=<key>] - [--merged [<commit>]] [--no-merged [<commit>]] - [--contains [<commit>]] [--no-contains [<commit>]] - [--points-at <object>] [--format=<format>] - [(-r | --remotes) | (-a | --all)] - [--list] [<pattern>...] -'git branch' [--track[=(direct|inherit)] | --no-track] [-f] - [--recurse-submodules] <branchname> [<start-point>] -'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] -'git branch' --unset-upstream [<branchname>] -'git branch' (-m | -M) [<oldbranch>] <newbranch> -'git branch' (-c | -C) [<oldbranch>] <newbranch> -'git branch' (-d | -D) [-r] <branchname>... -'git branch' --edit-description [<branchname>] +[synopsis] +git branch [--color[=<when>] | --no-color] [--show-current] + [-v [--abbrev=<n> | --no-abbrev]] + [--column[=<options>] | --no-column] [--sort=<key>] + [--merged [<commit>]] [--no-merged [<commit>]] + [--contains [<commit>]] [--no-contains [<commit>]] + [--points-at <object>] [--format=<format>] + [(-r|--remotes) | (-a|--all)] + [--list] [<pattern>...] +git branch [--track[=(direct|inherit)] | --no-track] [-f] + [--recurse-submodules] <branch-name> [<start-point>] +git branch (--set-upstream-to=<upstream>|-u <upstream>) [<branch-name>] +git branch --unset-upstream [<branch-name>] +git branch (-m|-M) [<old-branch>] <new-branch> +git branch (-c|-C) [<old-branch>] <new-branch> +git branch (-d|-D) [-r] <branch-name>... +git branch --edit-description [<branch-name>] DESCRIPTION ----------- @@ -49,173 +49,184 @@ With `--contains`, shows only the branches that contain the named commit named commit), `--no-contains` inverts it. With `--merged`, only branches merged into the named commit (i.e. the branches whose tip commits are reachable from the named commit) will be listed. With `--no-merged` only -branches not merged into the named commit will be listed. If the <commit> +branches not merged into the named commit will be listed. If the _<commit>_ argument is missing it defaults to `HEAD` (i.e. the tip of the current branch). -The command's second form creates a new branch head named <branchname> -which points to the current `HEAD`, or <start-point> if given. As a -special case, for <start-point>, you may use `"A...B"` as a shortcut for -the merge base of `A` and `B` if there is exactly one merge base. You -can leave out at most one of `A` and `B`, in which case it defaults to -`HEAD`. +The command's second form creates a new branch head named _<branch-name>_ +which points to the current `HEAD`, or _<start-point>_ if given. As a +special case, for _<start-point>_, you may use `<rev-A>...<rev-B>` as a +shortcut for the merge base of _<rev-A>_ and _<rev-B>_ if there is exactly +one merge base. You can leave out at most one of _<rev-A>_ and _<rev-B>_, +in which case it defaults to `HEAD`. Note that this will create the new branch, but it will not switch the -working tree to it; use "git switch <newbranch>" to switch to the +working tree to it; use `git switch <new-branch>` to switch to the new branch. When a local branch is started off a remote-tracking branch, Git sets up the branch (specifically the `branch.<name>.remote` and `branch.<name>.merge` -configuration entries) so that 'git pull' will appropriately merge from +configuration entries) so that `git pull` will appropriately merge from the remote-tracking branch. This behavior may be changed via the global `branch.autoSetupMerge` configuration flag. That setting can be overridden by using the `--track` and `--no-track` options, and changed later using `git branch --set-upstream-to`. -With a `-m` or `-M` option, <oldbranch> will be renamed to <newbranch>. -If <oldbranch> had a corresponding reflog, it is renamed to match -<newbranch>, and a reflog entry is created to remember the branch -renaming. If <newbranch> exists, -M must be used to force the rename +With a `-m` or `-M` option, _<old-branch>_ will be renamed to _<new-branch>_. +If _<old-branch>_ had a corresponding reflog, it is renamed to match +_<new-branch>_, and a reflog entry is created to remember the branch +renaming. If _<new-branch>_ exists, `-M` must be used to force the rename to happen. The `-c` and `-C` options have the exact same semantics as `-m` and `-M`, except instead of the branch being renamed, it will be copied to a new name, along with its config and reflog. -With a `-d` or `-D` option, `<branchname>` will be deleted. You may +With a `-d` or `-D` option, _<branch-name>_ will be deleted. You may specify more than one branch for deletion. If the branch currently has a reflog then the reflog will also be deleted. Use `-r` together with `-d` to delete remote-tracking branches. Note, that it only makes sense to delete remote-tracking branches if they no longer exist -in the remote repository or if 'git fetch' was configured not to fetch -them again. See also the 'prune' subcommand of linkgit:git-remote[1] for a +in the remote repository or if `git fetch` was configured not to fetch +them again. See also the `prune` subcommand of linkgit:git-remote[1] for a way to clean up all obsolete remote-tracking branches. OPTIONS ------- --d:: ---delete:: +`-d`:: +`--delete`:: Delete a branch. The branch must be fully merged in its upstream branch, or in `HEAD` if no upstream was set with `--track` or `--set-upstream-to`. --D:: +`-D`:: Shortcut for `--delete --force`. ---create-reflog:: +`--create-reflog`:: Create the branch's reflog. This activates recording of all changes made to the branch ref, enabling use of date - based sha1 expressions such as "<branchname>@\{yesterday}". + based sha1 expressions such as `<branch-name>@{yesterday}`. Note that in non-bare repositories, reflogs are usually enabled by default by the `core.logAllRefUpdates` config option. The negated form `--no-create-reflog` only overrides an earlier `--create-reflog`, but currently does not negate the setting of `core.logAllRefUpdates`. --f:: ---force:: - Reset <branchname> to <start-point>, even if <branchname> exists - already. Without `-f`, 'git branch' refuses to change an existing branch. +`-f`:: +`--force`:: + Reset _<branch-name>_ to _<start-point>_, even if _<branch-name>_ exists + already. Without `-f`, `git branch` refuses to change an existing branch. In combination with `-d` (or `--delete`), allow deleting the branch irrespective of its merged status, or whether it even points to a valid commit. In combination with `-m` (or `--move`), allow renaming the branch even if the new branch name already exists, the same applies for `-c` (or `--copy`). + -Note that 'git branch -f <branchname> [<start-point>]', even with '-f', -refuses to change an existing branch `<branchname>` that is checked out +Note that `git branch -f <branch-name> [<start-point>]`, even with `-f`, +refuses to change an existing branch _<branch-name>_ that is checked out in another worktree linked to the same repository. --m:: ---move:: +`-m`:: +`--move`:: Move/rename a branch, together with its config and reflog. --M:: +`-M`:: Shortcut for `--move --force`. --c:: ---copy:: +`-c`:: +`--copy`:: Copy a branch, together with its config and reflog. --C:: +`-C`:: Shortcut for `--copy --force`. ---color[=<when>]:: +`--color[=<when>]`:: Color branches to highlight current, local, and remote-tracking branches. - The value must be always (the default), never, or auto. + The value must be `always` (the default), `never`, or `auto`. ---no-color:: +`--no-color`:: Turn off branch colors, even when the configuration file gives the default to color output. Same as `--color=never`. --i:: ---ignore-case:: +`-i`:: +`--ignore-case`:: Sorting and filtering branches are case insensitive. ---omit-empty:: +`--omit-empty`:: Do not print a newline after formatted refs where the format expands to the empty string. ---column[=<options>]:: ---no-column:: +`--column[=<options>]`:: +`--no-column`:: Display branch listing in columns. See configuration variable `column.branch` for option syntax. `--column` and `--no-column` - without options are equivalent to 'always' and 'never' respectively. + without options are equivalent to `always` and `never` respectively. + This option is only applicable in non-verbose mode. --r:: ---remotes:: - List or delete (if used with -d) the remote-tracking branches. +`--sort=<key>`:: + Sort based on _<key>_. Prefix `-` to sort in descending + order of the value. You may use the `--sort=<key>` option + multiple times, in which case the last key becomes the primary + key. The keys supported are the same as those in linkgit:git-for-each-ref[1]. + Sort order defaults to the value configured for the + `branch.sort` variable if it exists, or to sorting based on the + full refname (including `refs/...` prefix). This lists + detached `HEAD` (if present) first, then local branches and + finally remote-tracking branches. See linkgit:git-config[1]. + +`-r`:: +`--remotes`:: + List or delete (if used with `-d`) the remote-tracking branches. Combine with `--list` to match the optional pattern(s). --a:: ---all:: +`-a`:: +`--all`:: List both remote-tracking branches and local branches. Combine with `--list` to match optional pattern(s). --l:: ---list:: +`-l`:: +`--list`:: List branches. With optional `<pattern>...`, e.g. `git branch --list 'maint-*'`, list only the branches that match the pattern(s). ---show-current:: - Print the name of the current branch. In detached HEAD state, +`--show-current`:: + Print the name of the current branch. In detached `HEAD` state, nothing is printed. --v:: --vv:: ---verbose:: +`-v`:: +`-vv`:: +`--verbose`:: When in list mode, show sha1 and commit subject line for each head, along with relationship to upstream branch (if any). If given twice, print the path of the linked worktree (if any) and the name of the upstream branch, as well (see also `git remote show <remote>`). Note that the - current worktree's HEAD will not have its path printed (it will always + current worktree's `HEAD` will not have its path printed (it will always be your current directory). --q:: ---quiet:: +`-q`:: +`--quiet`:: Be more quiet when creating or deleting a branch, suppressing non-error messages. ---abbrev=<n>:: +`--abbrev=<n>`:: In the verbose listing that show the commit object name, - show the shortest prefix that is at least '<n>' hexdigits + show the shortest prefix that is at least _<n>_ hexdigits long that uniquely refers the object. The default value is 7 and can be overridden by the `core.abbrev` config option. ---no-abbrev:: +`--no-abbrev`:: Display the full sha1s in the output listing rather than abbreviating them. --t:: ---track[=(direct|inherit)]:: +`-t`:: +`--track[=(direct|inherit)]`:: When creating a new branch, set up `branch.<name>.remote` and `branch.<name>.merge` configuration entries to set "upstream" tracking configuration for the new branch. This @@ -229,7 +240,7 @@ The exact upstream branch is chosen depending on the optional argument: itself as the upstream; `--track=inherit` means to copy the upstream configuration of the start-point branch. + -The branch.autoSetupMerge configuration variable specifies how `git switch`, +The `branch.autoSetupMerge` configuration variable specifies how `git switch`, `git checkout` and `git branch` should behave when neither `--track` nor `--no-track` are specified: + @@ -238,106 +249,94 @@ were given whenever the start-point is a remote-tracking branch. `false` behaves as if `--no-track` were given. `always` behaves as though `--track=direct` were given. `inherit` behaves as though `--track=inherit` were given. `simple` behaves as though `--track=direct` were given only when -the start-point is a remote-tracking branch and the new branch has the same +the _<start-point>_ is a remote-tracking branch and the new branch has the same name as the remote branch. + See linkgit:git-pull[1] and linkgit:git-config[1] for additional discussion on how the `branch.<name>.remote` and `branch.<name>.merge` options are used. ---no-track:: +`--no-track`:: Do not set up "upstream" configuration, even if the - branch.autoSetupMerge configuration variable is set. + `branch.autoSetupMerge` configuration variable is set. ---recurse-submodules:: - THIS OPTION IS EXPERIMENTAL! Causes the current command to +`--recurse-submodules`:: + THIS OPTION IS EXPERIMENTAL! Cause the current command to recurse into submodules if `submodule.propagateBranches` is enabled. See `submodule.propagateBranches` in linkgit:git-config[1]. Currently, only branch creation is supported. + -When used in branch creation, a new branch <branchname> will be created +When used in branch creation, a new branch _<branch-name>_ will be created in the superproject and all of the submodules in the superproject's -<start-point>. In submodules, the branch will point to the submodule -commit in the superproject's <start-point> but the branch's tracking +_<start-point>_. In submodules, the branch will point to the submodule +commit in the superproject's _<start-point>_ but the branch's tracking information will be set up based on the submodule's branches and remotes e.g. `git branch --recurse-submodules topic origin/main` will create the submodule branch "topic" that points to the submodule commit in the superproject's "origin/main", but tracks the submodule's "origin/main". ---set-upstream:: +`--set-upstream`:: As this option had confusing syntax, it is no longer supported. Please use `--track` or `--set-upstream-to` instead. --u <upstream>:: ---set-upstream-to=<upstream>:: - Set up <branchname>'s tracking information so <upstream> is - considered <branchname>'s upstream branch. If no <branchname> +`-u <upstream>`:: +`--set-upstream-to=<upstream>`:: + Set up _<branch-name>_'s tracking information so _<upstream>_ is + considered _<branch-name>_'s upstream branch. If no _<branch-name>_ is specified, then it defaults to the current branch. ---unset-upstream:: - Remove the upstream information for <branchname>. If no branch +`--unset-upstream`:: + Remove the upstream information for _<branch-name>_. If no branch is specified it defaults to the current branch. ---edit-description:: +`--edit-description`:: Open an editor and edit the text to explain what the branch is for, to be used by various other commands (e.g. `format-patch`, `request-pull`, and `merge` (if enabled)). Multi-line explanations may be used. ---contains [<commit>]:: - Only list branches which contain the specified commit (HEAD +`--contains [<commit>]`:: + Only list branches which contain _<commit>_ (`HEAD` if not specified). Implies `--list`. ---no-contains [<commit>]:: - Only list branches which don't contain the specified commit - (HEAD if not specified). Implies `--list`. +`--no-contains [<commit>]`:: + Only list branches which don't contain _<commit>_ + (`HEAD` if not specified). Implies `--list`. ---merged [<commit>]:: - Only list branches whose tips are reachable from the - specified commit (HEAD if not specified). Implies `--list`. +`--merged [<commit>]`:: + Only list branches whose tips are reachable from + _<commit>_ (`HEAD` if not specified). Implies `--list`. ---no-merged [<commit>]:: - Only list branches whose tips are not reachable from the - specified commit (HEAD if not specified). Implies `--list`. +`--no-merged [<commit>]`:: + Only list branches whose tips are not reachable from + _<commit>_ (`HEAD` if not specified). Implies `--list`. -<branchname>:: +`--points-at <object>`:: + Only list branches of _<object>_. + +`--format <format>`:: + A string that interpolates `%(fieldname)` from a branch ref being shown + and the object it points at. _<format>_ is the same as + that of linkgit:git-for-each-ref[1]. + +_<branch-name>_:: The name of the branch to create or delete. The new branch name must pass all checks defined by linkgit:git-check-ref-format[1]. Some of these checks may restrict the characters allowed in a branch name. -<start-point>:: +_<start-point>_:: The new branch head will point to this commit. It may be given as a branch name, a commit-id, or a tag. If this - option is omitted, the current HEAD will be used instead. + option is omitted, the current `HEAD` will be used instead. -<oldbranch>:: +_<old-branch>_:: The name of an existing branch. If this option is omitted, the name of the current branch will be used instead. -<newbranch>:: +_<new-branch>_:: The new name for an existing branch. The same restrictions as for - <branchname> apply. - ---sort=<key>:: - Sort based on the key given. Prefix `-` to sort in descending - order of the value. You may use the --sort=<key> option - multiple times, in which case the last key becomes the primary - key. The keys supported are the same as those in `git - for-each-ref`. Sort order defaults to the value configured for the - `branch.sort` variable if it exists, or to sorting based on the - full refname (including `refs/...` prefix). This lists - detached HEAD (if present) first, then local branches and - finally remote-tracking branches. See linkgit:git-config[1]. - - ---points-at <object>:: - Only list branches of the given object. - ---format <format>:: - A string that interpolates `%(fieldname)` from a branch ref being shown - and the object it points at. The format is the same as - that of linkgit:git-for-each-ref[1]. + _<branch-name>_ apply. CONFIGURATION ------------- @@ -374,7 +373,7 @@ $ git branch -D test <2> ------------ + <1> Delete the remote-tracking branches "todo", "html" and "man". The next - 'fetch' or 'pull' will create them again unless you configure them not to. + `git fetch` or `git pullè will create them again unless you configure them not to. See linkgit:git-fetch[1]. <2> Delete the "test" branch even if the "master" branch (or whichever branch is currently checked out) does not have all commits from the test branch. @@ -386,8 +385,8 @@ $ git branch -r -l '<remote>/<pattern>' <1> $ git for-each-ref 'refs/remotes/<remote>/<pattern>' <2> ------------ + -<1> Using `-a` would conflate <remote> with any local branches you happen to - have been prefixed with the same <remote> pattern. +<1> Using `-a` would conflate _<remote>_ with any local branches you happen to + have been prefixed with the same _<remote>_ pattern. <2> `for-each-ref` can take a wide range of options. See linkgit:git-for-each-ref[1] Patterns will normally need quoting. @@ -396,24 +395,24 @@ NOTES ----- If you are creating a branch that you want to switch to immediately, -it is easier to use the "git switch" command with its `-c` option to +it is easier to use the `git switch` command with its `-c` option to do the same thing with a single command. The options `--contains`, `--no-contains`, `--merged` and `--no-merged` serve four related but different purposes: - `--contains <commit>` is used to find all branches which will need - special attention if <commit> were to be rebased or amended, since those - branches contain the specified <commit>. + special attention if _<commit>_ were to be rebased or amended, since those + branches contain the specified _<commit>_. - `--no-contains <commit>` is the inverse of that, i.e. branches that don't - contain the specified <commit>. + contain the specified _<commit>_. - `--merged` is used to find all branches which can be safely deleted, - since those branches are fully contained by HEAD. + since those branches are fully contained by `HEAD`. - `--no-merged` is used to find branches which are candidates for merging - into HEAD, since those branches are not fully contained by HEAD. + into `HEAD`, since those branches are not fully contained by `HEAD`. include::ref-reachability-filters.adoc[] @@ -422,8 +421,8 @@ SEE ALSO linkgit:git-check-ref-format[1], linkgit:git-fetch[1], linkgit:git-remote[1], -link:user-manual.html#what-is-a-branch[``Understanding history: What is -a branch?''] in the Git User's Manual. +link:user-manual.html#what-is-a-branch["Understanding history: What is +a branch?"] in the Git User's Manual. GIT --- diff --git a/Documentation/git-cat-file.adoc b/Documentation/git-cat-file.adoc index 30359f5dbd..fc4b92f104 100644 --- a/Documentation/git-cat-file.adoc +++ b/Documentation/git-cat-file.adoc @@ -81,6 +81,25 @@ OPTIONS end-of-line conversion, etc). In this case, `<object>` has to be of the form `<tree-ish>:<path>`, or `:<path>`. +--filter=<filter-spec>:: +--no-filter:: + Omit objects from the list of printed objects. This can only be used in + combination with one of the batched modes. Excluded objects that have + been explicitly requested via any of the batch modes that read objects + via standard input (`--batch`, `--batch-check`) will be reported as + "filtered". Excluded objects in `--batch-all-objects` mode will not be + printed at all. The '<filter-spec>' may be one of the following: ++ +The form '--filter=blob:none' omits all blobs. ++ +The form '--filter=blob:limit=<n>[kmg]' omits blobs of size at least n +bytes or units. n may be zero. The suffixes k, m, and g can be used to name +units in KiB, MiB, or GiB. For example, 'blob:limit=1k' is the same as +'blob:limit=1024'. ++ +The form '--filter=object:type=(tag|commit|tree|blob)' omits all objects which +are not of the requested type. + --path=<path>:: For use with `--textconv` or `--filters`, to allow specifying an object name and a path separately, e.g. when it is difficult to figure out @@ -340,6 +359,13 @@ the repository, then `cat-file` will ignore any custom format and print: <object> SP missing LF ------------ +If a name is specified on stdin that is filtered out via `--filter=`, +then `cat-file` will ignore any custom format and print: + +------------ +<object> SP excluded LF +------------ + If a name is specified that might refer to more than one object (an ambiguous short sha), then `cat-file` will ignore any custom format and print: ------------ diff --git a/Documentation/git-maintenance.adoc b/Documentation/git-maintenance.adoc index 0450d74aff..3a1e2a69b6 100644 --- a/Documentation/git-maintenance.adoc +++ b/Documentation/git-maintenance.adoc @@ -126,13 +126,17 @@ loose-objects:: objects that already exist in a pack-file; concurrent Git processes will examine the pack-file for the object data instead of the loose object. Second, it creates a new pack-file (starting with "loose-") - containing a batch of loose objects. The batch size is limited to 50 - thousand objects to prevent the job from taking too long on a - repository with many loose objects. The `gc` task writes unreachable - objects as loose objects to be cleaned up by a later step only if - they are not re-added to a pack-file; for this reason it is not - advisable to enable both the `loose-objects` and `gc` tasks at the - same time. + containing a batch of loose objects. ++ +The batch size defaults to fifty thousand objects to prevent the job from +taking too long on a repository with many loose objects. Use the +`maintenance.loose-objects.batchSize` config option to adjust this size, +including a value of `0` to remove the limit. ++ +The `gc` task writes unreachable objects as loose objects to be cleaned up +by a later step only if they are not re-added to a pack-file; for this +reason it is not advisable to enable both the `loose-objects` and `gc` +tasks at the same time. incremental-repack:: The `incremental-repack` job repacks the object directory @@ -158,6 +162,10 @@ pack-refs:: need to iterate across many references. See linkgit:git-pack-refs[1] for more information. +reflog-expire:: + The `reflog-expire` task deletes any entries in the reflog older than the + expiry threshold. See linkgit:git-reflog[1] for more information. + OPTIONS ------- --auto:: diff --git a/Documentation/git-mv.adoc b/Documentation/git-mv.adoc index dc1bf61534..f707e998f7 100644 --- a/Documentation/git-mv.adoc +++ b/Documentation/git-mv.adoc @@ -8,19 +8,18 @@ git-mv - Move or rename a file, a directory, or a symlink SYNOPSIS -------- -[verse] -'git mv' [<options>] <source>... <destination> + +[synopsis] +git mv [-v] [-f] [-n] [-k] <source> <destination> +git mv [-v] [-f] [-n] [-k] <source>... <destination-directory> DESCRIPTION ----------- Move or rename a file, directory, or symlink. - git mv [-v] [-f] [-n] [-k] <source> <destination> - git mv [-v] [-f] [-n] [-k] <source> ... <destination-directory> - -In the first form, it renames <source>, which must exist and be either -a file, symlink or directory, to <destination>. -In the second form, the last argument has to be an existing +In the first form, it renames _<source>_, which must exist and be either +a file, symlink or directory, to _<destination>_. +In the second form, _<destination-directory>_ has to be an existing directory; the given sources will be moved into this directory. The index is updated after successful completion, but the change must still be @@ -28,20 +27,20 @@ committed. OPTIONS ------- --f:: ---force:: +`-f`:: +`--force`:: Force renaming or moving of a file even if the <destination> exists. --k:: +`-k`:: Skip move or rename actions which would lead to an error condition. An error happens when a source is neither existing nor controlled by Git, or when it would overwrite an existing file unless `-f` is given. --n:: ---dry-run:: +`-n`:: +`--dry-run`:: Do nothing; only show what would happen --v:: ---verbose:: +`-v`:: +`--verbose`:: Report the names of files as they are moved. SUBMODULES @@ -49,8 +48,8 @@ SUBMODULES Moving a submodule using a gitfile (which means they were cloned with a Git version 1.7.8 or newer) will update the gitfile and core.worktree setting to make the submodule work in the new location. -It also will attempt to update the submodule.<name>.path setting in -the linkgit:gitmodules[5] file and stage that file (unless -n is used). +It also will attempt to update the `submodule.<name>.path` setting in +the linkgit:gitmodules[5] file and stage that file (unless `-n` is used). BUGS ---- diff --git a/Documentation/git-pack-refs.adoc b/Documentation/git-pack-refs.adoc index 2dcabaf74c..652c549771 100644 --- a/Documentation/git-pack-refs.adoc +++ b/Documentation/git-pack-refs.adoc @@ -88,10 +88,10 @@ Do not pack refs matching the given `glob(7)` pattern. Repetitions of this optio accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of patterns. If a ref is already packed, including it with `--exclude` will not unpack it. - ++ When used with `--all`, pack only loose refs which do not match any of the provided `--exclude` patterns. - ++ When used with `--include`, refs provided to `--include`, minus refs that are provided to `--exclude` will be packed. diff --git a/Documentation/git-reflog.adoc b/Documentation/git-reflog.adoc index a929c52982..b55c060569 100644 --- a/Documentation/git-reflog.adoc +++ b/Documentation/git-reflog.adoc @@ -16,6 +16,7 @@ SYNOPSIS [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...] 'git reflog delete' [--rewrite] [--updateref] [--dry-run | -n] [--verbose] <ref>@{<specifier>}... +'git reflog drop' [--all [--single-worktree] | <refs>...] 'git reflog exists' <ref> DESCRIPTION @@ -48,10 +49,14 @@ and not reachable from the current tip, are removed from the reflog. This is typically not used directly by end users -- instead, see linkgit:git-gc[1]. -The "delete" subcommand deletes single entries from the reflog. Its -argument must be an _exact_ entry (e.g. "`git reflog delete -master@{2}`"). This subcommand is also typically not used directly by -end users. +The "delete" subcommand deletes single entries from the reflog, but +not the reflog itself. Its argument must be an _exact_ entry (e.g. "`git +reflog delete master@{2}`"). This subcommand is also typically not used +directly by end users. + +The "drop" subcommand completely removes the reflog for the specified +references. This is in contrast to "expire" and "delete", both of which +can be used to delete reflog entries, but not the reflog itself. The "exists" subcommand checks whether a ref has a reflog. It exits with zero status if the reflog exists, and non-zero status if it does @@ -132,6 +137,16 @@ Options for `delete` `--dry-run`, and `--verbose`, with the same meanings as when they are used with `expire`. +Options for `drop` +~~~~~~~~~~~~~~~~~~~~ + +--all:: + Drop the reflogs of all references from all worktrees. + +--single-worktree:: + By default when `--all` is specified, reflogs from all working + trees are dropped. This option limits the processing to reflogs + from the current working tree only. GIT --- diff --git a/Documentation/git-repack.adoc b/Documentation/git-repack.adoc index 5852a5c973..e1cd75eebe 100644 --- a/Documentation/git-repack.adoc +++ b/Documentation/git-repack.adoc @@ -77,15 +77,18 @@ to the new separate pack will be written. Only useful with `--cruft -d`. --max-cruft-size=<n>:: - Repack cruft objects into packs as large as `<n>` bytes before - creating new packs. As long as there are enough cruft packs - smaller than `<n>`, repacking will cause a new cruft pack to - be created containing objects from any combined cruft packs, - along with any new unreachable objects. Cruft packs larger than - `<n>` will not be modified. When the new cruft pack is larger - than `<n>` bytes, it will be split into multiple packs, all of - which are guaranteed to be at most `<n>` bytes in size. Only - useful with `--cruft -d`. + Overrides `--max-pack-size` for cruft packs. Inherits the value of + `--max-pack-size` (if any) by default. See the documentation for + `--max-pack-size` for more details. + +--combine-cruft-below-size=<n>:: + When generating cruft packs without pruning, only repack + existing cruft packs whose size is strictly less than `<n>`, + where `<n>` represents a number of bytes, which can optionally + be suffixed with "k", "m", or "g". Cruft packs whose size is + greater than or equal to `<n>` are left as-is and not repacked. + Useful when you want to avoid repacking large cruft pack(s) in + repositories that have many and/or large unreachable objects. --expire-to=<dir>:: Write a cruft pack containing pruned objects (if any) to the diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc index 79ad5643ee..53ab88c545 100644 --- a/Documentation/git-reset.adoc +++ b/Documentation/git-reset.adoc @@ -7,23 +7,23 @@ git-reset - Reset current HEAD to the specified state SYNOPSIS -------- -[verse] -'git reset' [-q] [<tree-ish>] [--] <pathspec>... -'git reset' [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>] -'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...] -'git reset' [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>] +[synopsis] +git reset [-q] [<tree-ish>] [--] <pathspec>... +git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>] +git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...] +git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>] DESCRIPTION ----------- -In the first three forms, copy entries from `<tree-ish>` to the index. -In the last form, set the current branch head (`HEAD`) to `<commit>`, +In the first three forms, copy entries from _<tree-ish>_ to the index. +In the last form, set the current branch head (`HEAD`) to _<commit>_, optionally modifying index and working tree to match. -The `<tree-ish>`/`<commit>` defaults to `HEAD` in all forms. +The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms. -'git reset' [-q] [<tree-ish>] [--] <pathspec>...:: -'git reset' [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]:: +`git reset [-q] [<tree-ish>] [--] <pathspec>...`:: +`git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`:: These forms reset the index entries for all paths that match the - `<pathspec>` to their state at `<tree-ish>`. (It does not affect + _<pathspec>_ to their state at _<tree-ish>_. (It does not affect the working tree or the current branch.) + This means that `git reset <pathspec>` is the opposite of `git add @@ -37,30 +37,30 @@ and specifying a commit with `--source`, you can copy the contents of a path out of a commit to the index and to the working tree in one go. -'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...]:: +`git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`:: Interactively select hunks in the difference between the index - and `<tree-ish>` (defaults to `HEAD`). The chosen hunks are applied + and _<tree-ish>_ (defaults to `HEAD`). The chosen hunks are applied in reverse to the index. + This means that `git reset -p` is the opposite of `git add -p`, i.e. -you can use it to selectively reset hunks. See the ``Interactive Mode'' +you can use it to selectively reset hunks. See the "Interactive Mode" section of linkgit:git-add[1] to learn how to operate the `--patch` mode. -'git reset' [<mode>] [<commit>]:: - This form resets the current branch head to `<commit>` and - possibly updates the index (resetting it to the tree of `<commit>`) and - the working tree depending on `<mode>`. Before the operation, `ORIG_HEAD` - is set to the tip of the current branch. If `<mode>` is omitted, - defaults to `--mixed`. The `<mode>` must be one of the following: +`git reset [<mode>] [<commit>]`:: + This form resets the current branch head to _<commit>_ and + possibly updates the index (resetting it to the tree of _<commit>_) and + the working tree depending on _<mode>_. Before the operation, `ORIG_HEAD` + is set to the tip of the current branch. If _<mode>_ is omitted, + defaults to `--mixed`. The _<mode>_ must be one of the following: + -- ---soft:: +`--soft`:: Does not touch the index file or the working tree at all (but - resets the head to `<commit>`, just like all modes do). This leaves + resets the head to _<commit>_, just like all modes do). This leaves all your changed files "Changes to be committed", as `git status` would put it. ---mixed:: +`--mixed`:: Resets the index but not the working tree (i.e., the changed files are preserved but not marked for commit) and reports what has not been updated. This is the default action. @@ -68,33 +68,33 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. If `-N` is specified, removed paths are marked as intent-to-add (see linkgit:git-add[1]). ---hard:: +`--hard`:: Resets the index and working tree. Any changes to tracked files in the - working tree since `<commit>` are discarded. Any untracked files or + working tree since _<commit>_ are discarded. Any untracked files or directories in the way of writing any tracked files are simply deleted. ---merge:: +`--merge`:: Resets the index and updates the files in the working tree that are - different between `<commit>` and `HEAD`, but keeps those which are + different between _<commit>_ and `HEAD`, but keeps those which are different between the index and working tree (i.e. which have changes which have not been added). - If a file that is different between `<commit>` and the index has + If a file that is different between _<commit>_ and the index has unstaged changes, reset is aborted. + In other words, `--merge` does something like a `git read-tree -u -m <commit>`, but carries forward unmerged index entries. ---keep:: +`--keep`:: Resets index entries and updates files in the working tree that are - different between `<commit>` and `HEAD`. - If a file that is different between `<commit>` and `HEAD` has local + different between _<commit>_ and `HEAD`. + If a file that is different between _<commit>_ and `HEAD` has local changes, reset is aborted. ---[no-]recurse-submodules:: - When the working tree is updated, using --recurse-submodules will +`--[no-]recurse-submodules`:: + When the working tree is updated, using `--recurse-submodules` will also recursively reset the working tree of all active submodules according to the commit recorded in the superproject, also setting - the submodules' HEAD to be detached at that commit. + the submodules' `HEAD` to be detached at that commit. -- See "Reset, restore and revert" in linkgit:git[1] for the differences @@ -104,31 +104,31 @@ between the three commands. OPTIONS ------- --q:: ---quiet:: +`-q`:: +`--quiet`:: Be quiet, only report errors. ---refresh:: ---no-refresh:: +`--refresh`:: +`--no-refresh`:: Refresh the index after a mixed reset. Enabled by default. ---pathspec-from-file=<file>:: - Pathspec is passed in `<file>` instead of commandline args. If - `<file>` is exactly `-` then standard input is used. Pathspec - elements are separated by LF or CR/LF. Pathspec elements can be +`--pathspec-from-file=<file>`:: + Pathspec is passed in _<file>_ instead of commandline args. If + _<file>_ is exactly `-` then standard input is used. Pathspec + elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). See also `--pathspec-file-nul` and global `--literal-pathspecs`. ---pathspec-file-nul:: +`--pathspec-file-nul`:: Only meaningful with `--pathspec-from-file`. Pathspec elements are - separated with NUL character and all other characters are taken + separated with _NUL_ character and all other characters are taken literally (including newlines and quotes). -\--:: +`--`:: Do not interpret any more arguments as options. -<pathspec>...:: +`<pathspec>...`:: Limits the paths affected by the operation. + For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. @@ -348,7 +348,7 @@ $ git commit ... <8> ------------ + <1> First, reset the history back one commit so that we remove the original - commit, but leave the working tree with all the changes. The -N ensures + commit, but leave the working tree with all the changes. The `-N` ensures that any new files added with `HEAD` are still marked so that `git add -p` will find them. <2> Next, we interactively select diff hunks to add using the `git add -p` @@ -458,7 +458,7 @@ working index HEAD target working index HEAD --keep B C C .... -`reset --merge` is meant to be used when resetting out of a conflicted +`git reset --merge` is meant to be used when resetting out of a conflicted merge. Any mergy operation guarantees that the working tree file that is involved in the merge does not have a local change with respect to the index before it starts, and that it writes the result out to the working tree. So if @@ -467,7 +467,7 @@ between the index and the working tree, then it means that we are not resetting out from a state that a mergy operation left after failing with a conflict. That is why we disallow `--merge` option in this case. -`reset --keep` is meant to be used when removing some of the last +`git reset --keep` is meant to be used when removing some of the last commits in the current branch while keeping changes in the working tree. If there could be conflicts between the changes in the commit we want to remove and the changes in the working tree we want to keep, diff --git a/Documentation/git-restore.adoc b/Documentation/git-restore.adoc index 751f01b441..877b7772e6 100644 --- a/Documentation/git-restore.adoc +++ b/Documentation/git-restore.adoc @@ -51,9 +51,6 @@ leave out at most one of _<rev-A>__ and _<rev-B>_, in which case it defaults to restore source and the restore location. See the "Interactive Mode" section of linkgit:git-add[1] to learn how to operate the `--patch` mode. -+ -Note that `--patch` can accept no pathspec and will prompt to restore -all modified paths. `-W`:: `--worktree`:: diff --git a/Documentation/git-rm.adoc b/Documentation/git-rm.adoc index 363a26934f..b5ead86796 100644 --- a/Documentation/git-rm.adoc +++ b/Documentation/git-rm.adoc @@ -7,10 +7,10 @@ git-rm - Remove files from the working tree and from the index SYNOPSIS -------- -[verse] -'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] - [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]] - [--] [<pathspec>...] +[synopsis] +git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] + [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]] + [--] [<pathspec>...] DESCRIPTION ----------- @@ -30,7 +30,7 @@ sparse-checkouts are in use (see linkgit:git-sparse-checkout[1]), OPTIONS ------- -<pathspec>...:: +`<pathspec>...`:: Files to remove. A leading directory name (e.g. `dir` to remove `dir/file1` and `dir/file2`) can be given to remove all files in the directory, and recursively all sub-directories, but this @@ -43,57 +43,57 @@ directories `d` and `d2`, there is a difference between using `git rm 'd*'` and `git rm 'd/*'`, as the former will also remove all of directory `d2`. + -For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. +For more details, see the _<pathspec>_ entry in linkgit:gitglossary[7]. --f:: ---force:: +`-f`:: +`--force`:: Override the up-to-date check. --n:: ---dry-run:: +`-n`:: +`--dry-run`:: Don't actually remove any file(s). Instead, just show if they exist in the index and would otherwise be removed by the command. --r:: +`-r`:: Allow recursive removal when a leading directory name is given. -\--:: +`--`:: This option can be used to separate command-line options from the list of files, (useful when filenames might be mistaken for command-line options). ---cached:: +`--cached`:: Use this option to unstage and remove paths only from the index. Working tree files, whether modified or not, will be left alone. ---ignore-unmatch:: +`--ignore-unmatch`:: Exit with a zero status even if no files matched. ---sparse:: +`--sparse`:: Allow updating index entries outside of the sparse-checkout cone. Normally, `git rm` refuses to update index entries whose paths do not fit within the sparse-checkout cone. See linkgit:git-sparse-checkout[1] for more. --q:: ---quiet:: +`-q`:: +`--quiet`:: `git rm` normally outputs one line (in the form of an `rm` command) for each file removed. This option suppresses that output. ---pathspec-from-file=<file>:: - Pathspec is passed in `<file>` instead of commandline args. If - `<file>` is exactly `-` then standard input is used. Pathspec - elements are separated by LF or CR/LF. Pathspec elements can be +`--pathspec-from-file=<file>`:: + Pathspec is passed in _<file>_ instead of args. If + _<file>_ is exactly `-` then standard input is used. Pathspec + elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). See also `--pathspec-file-nul` and global `--literal-pathspecs`. ---pathspec-file-nul:: +`--pathspec-file-nul`:: Only meaningful with `--pathspec-from-file`. Pathspec elements are - separated with NUL character and all other characters are taken + separated with _NUL_ character and all other characters are taken literally (including newlines and quotes). @@ -153,15 +153,15 @@ SUBMODULES ---------- Only submodules using a gitfile (which means they were cloned with a Git version 1.7.8 or newer) will be removed from the work -tree, as their repository lives inside the .git directory of the +tree, as their repository lives inside the `.git` directory of the superproject. If a submodule (or one of those nested inside it) -still uses a .git directory, `git rm` will move the submodules +still uses a `.git` directory, `git rm` moves the submodules git directory into the superprojects git directory to protect -the submodule's history. If it exists the submodule.<name> section +the submodule's history. If it exists the `submodule.<name>` section in the linkgit:gitmodules[5] file will also be removed and that file -will be staged (unless --cached or -n are used). +will be staged (unless `--cached` or `-n` are used). -A submodule is considered up to date when the HEAD is the same as +A submodule is considered up to date when the `HEAD` is the same as recorded in the index, no tracked files are modified and no untracked files that aren't ignored are present in the submodule's work tree. Ignored files are deemed expendable and won't stop a submodule's work diff --git a/Documentation/git-update-ref.adoc b/Documentation/git-update-ref.adoc index 9e6935d38d..9310ce9768 100644 --- a/Documentation/git-update-ref.adoc +++ b/Documentation/git-update-ref.adoc @@ -7,8 +7,10 @@ git-update-ref - Update the object name stored in a ref safely SYNOPSIS -------- -[verse] -'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<old-oid>] | [--create-reflog] <ref> <new-oid> [<old-oid>] | --stdin [-z]) +[synopsis] +git update-ref [-m <reason>] [--no-deref] -d <ref> [<old-oid>] +git update-ref [-m <reason>] [--no-deref] [--create-reflog] <ref> <new-oid> [<old-oid>] +git update-ref [-m <reason>] [--no-deref] --stdin [-z] [--batch-updates] DESCRIPTION ----------- @@ -57,6 +59,14 @@ performs all modifications together. Specify commands of the form: With `--create-reflog`, update-ref will create a reflog for each ref even if one would not ordinarily be created. +With `--batch-updates`, update-ref executes the updates in a batch but allows +individual updates to fail due to invalid or incorrect user input, applying only +the successful updates. However, system-related errors—such as I/O failures or +memory issues—will result in a full failure of all batched updates. Any failed +updates will be reported in the following format: + + rejected SP (<old-oid> | <old-target>) SP (<new-oid> | <new-target>) SP <rejection-reason> LF + Quote fields containing whitespace as if they were strings in C source code; i.e., surrounded by double-quotes and with backslash escapes. Use 40 "0" characters or the empty string to specify a zero value. To diff --git a/Documentation/git-version.adoc b/Documentation/git-version.adoc index 80fa7754a6..9462043a14 100644 --- a/Documentation/git-version.adoc +++ b/Documentation/git-version.adoc @@ -22,6 +22,14 @@ OPTIONS --build-options:: Include additional information about how git was built for diagnostic purposes. ++ +The libraries used to implement the SHA-1 and SHA-256 algorithms are displayed +in the form `SHA-1: <option>` and `SHA-256: <option>`. Note that the SHA-1 +options `SHA1_APPLE`, `SHA1_OPENSSL`, and `SHA1_BLK` do not use a collision +detection algorithm and thus may be vulnerable to known SHA-1 collision +attacks. When a faster SHA-1 implementation without collision detection is used +for only non-cryptographic purposes, the algorithm is displayed in the form +`non-collision-detecting-SHA-1: <option>`. GIT --- diff --git a/Documentation/merge-strategies.adoc b/Documentation/merge-strategies.adoc index 59f5ae36cc..9e034f447e 100644 --- a/Documentation/merge-strategies.adoc +++ b/Documentation/merge-strategies.adoc @@ -87,44 +87,33 @@ no-renames;; configuration variable. See also linkgit:git-diff[1] `--no-renames`. -subtree[=<path>];; - This option is a more advanced form of 'subtree' strategy, where - the strategy makes a guess on how two trees must be shifted to - match with each other when merging. Instead, the specified path - is prefixed (or stripped from the beginning) to make the shape of - two trees to match. - -recursive:: - This can only resolve two heads using a 3-way merge - algorithm. When there is more than one common - ancestor that can be used for 3-way merge, it creates a - merged tree of the common ancestors and uses that as - the reference tree for the 3-way merge. This has been - reported to result in fewer merge conflicts without - causing mismerges by tests done on actual merge commits - taken from Linux 2.6 kernel development history. - Additionally this can detect and handle merges involving - renames. It does not make use of detected copies. This was - the default strategy for resolving two heads from Git v0.99.9k - until v2.33.0. -+ -For a path that is a submodule, the same caution as 'ort' applies to this -strategy. -+ -The 'recursive' strategy takes the same options as 'ort'. However, -there are two additional options that 'ort' ignores (not documented -above) that are potentially useful with the 'recursive' strategy: +histogram;; + Deprecated synonym for `diff-algorithm=histogram`. patience;; Deprecated synonym for `diff-algorithm=patience`. -diff-algorithm=[patience|minimal|histogram|myers];; +diff-algorithm=[histogram|minimal|myers|patience];; Use a different diff algorithm while merging, which can help avoid mismerges that occur due to unimportant matching lines (such as braces from distinct functions). See also linkgit:git-diff[1] `--diff-algorithm`. Note that `ort` - specifically uses `diff-algorithm=histogram`, while `recursive` - defaults to the `diff.algorithm` config setting. + defaults to `diff-algorithm=histogram`, while regular diffs + currently default to the `diff.algorithm` config setting. + +subtree[=<path>];; + This option is a more advanced form of 'subtree' strategy, where + the strategy makes a guess on how two trees must be shifted to + match with each other when merging. Instead, the specified path + is prefixed (or stripped from the beginning) to make the shape of + two trees to match. + +recursive:: + This is now a synonym for `ort`. It was an alternative + implementation until v2.49.0, but was redirected to mean `ort` + in v2.50.0. The previous recursive strategy was the default + strategy for resolving two heads from Git v0.99.9k until + v2.33.0. resolve:: This can only resolve two heads (i.e. the current branch @@ -145,7 +134,7 @@ ours:: ignoring all changes from all other branches. It is meant to be used to supersede old development history of side branches. Note that this is different from the -Xours option to - the 'recursive' merge strategy. + the 'ort' merge strategy. subtree:: This is a modified `ort` strategy. When merging trees A and diff --git a/Documentation/mergetools/vimdiff.adoc b/Documentation/mergetools/vimdiff.adoc index befa86d692..ab915df408 100644 --- a/Documentation/mergetools/vimdiff.adoc +++ b/Documentation/mergetools/vimdiff.adoc @@ -86,7 +86,7 @@ command. + -- When `MERGED` is not present in the layout, you must "mark" one of the -buffers with an asterisk. That will become the buffer you need to edit and +buffers with an arobase (`@`). That will become the buffer you need to edit and save after resolving the conflicts. .... ------------------------------------------ diff --git a/Documentation/meson.build b/Documentation/meson.build index 5e556ce360..8d9cd98548 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -215,9 +215,9 @@ endif docs_backend = get_option('docs_backend') if docs_backend == 'auto' - if find_program('asciidoc', dirs: program_path, required: false).found() + if find_program('asciidoc', dirs: program_path, native: true, required: false).found() docs_backend = 'asciidoc' - elif find_program('asciidoctor', dirs: program_path, required: false).found() + elif find_program('asciidoctor', dirs: program_path, native: true, required: false).found() docs_backend = 'asciidoctor' else error('Neither asciidoc nor asciidoctor were found.') @@ -225,7 +225,7 @@ if docs_backend == 'auto' endif if docs_backend == 'asciidoc' - asciidoc = find_program('asciidoc', dirs: program_path) + asciidoc = find_program('asciidoc', dirs: program_path, native: true) asciidoc_html = 'xhtml11' asciidoc_docbook = 'docbook' xmlto_extra = [ ] @@ -254,7 +254,7 @@ if docs_backend == 'asciidoc' asciidoc_conf, ] elif docs_backend == 'asciidoctor' - asciidoctor = find_program('asciidoctor', dirs: program_path) + asciidoctor = find_program('asciidoctor', dirs: program_path, native: true) asciidoc_html = 'xhtml5' asciidoc_docbook = 'docbook5' xmlto_extra = [ @@ -296,7 +296,7 @@ if get_option('breaking_changes') asciidoc_common_options += ['--attribute', 'with-breaking-changes'] endif -xmlto = find_program('xmlto', dirs: program_path) +xmlto = find_program('xmlto', dirs: program_path, native: true) cmd_lists = [ 'cmds-ancillaryinterrogators.adoc', @@ -417,7 +417,7 @@ if get_option('docs').contains('html') pointing_to: 'git.html', ) - xsltproc = find_program('xsltproc', dirs: program_path) + xsltproc = find_program('xsltproc', dirs: program_path, native: true) user_manual_xml = custom_target( command: asciidoc_common_options + [ @@ -448,6 +448,7 @@ if get_option('docs').contains('html') ) articles = [ + 'BreakingChanges.adoc', 'DecisionMaking.adoc', 'MyFirstContribution.adoc', 'MyFirstObjectWalk.adoc', diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc index 1c403c1e40..d38875efda 100644 --- a/Documentation/rev-list-options.adoc +++ b/Documentation/rev-list-options.adoc @@ -361,6 +361,30 @@ ifdef::git-rev-list[] --progress=<header>:: Show progress reports on stderr as objects are considered. The `<header>` text will be printed with each progress update. + +-z:: + Instead of being newline-delimited, each outputted object and its + accompanying metadata is delimited using NUL bytes. Output is printed + in the following form: ++ +----------------------------------------------------------------------- +<OID> NUL [<token>=<value> NUL]... +----------------------------------------------------------------------- ++ +Additional object metadata, such as object paths or boundary objects, is +printed using the `<token>=<value>` form. Token values are printed as-is +without any encoding/truncation. An OID entry never contains a '=' character +and thus is used to signal the start of a new object record. Examples: ++ +----------------------------------------------------------------------- +<OID> NUL +<OID> NUL path=<path> NUL +<OID> NUL boundary=yes NUL +<OID> NUL missing=yes NUL [<token>=<value> NUL]... +----------------------------------------------------------------------- ++ +This mode is only compatible with the `--objects`, `--boundary`, and +`--missing` output options. endif::git-rev-list[] History Simplification diff --git a/Documentation/technical/multi-pack-index.adoc b/Documentation/technical/multi-pack-index.adoc index cc063b30be..ffda70aa13 100644 --- a/Documentation/technical/multi-pack-index.adoc +++ b/Documentation/technical/multi-pack-index.adoc @@ -164,19 +164,81 @@ objects_nr($H2) + objects_nr($H1) + i (in the C implementation, this is often computed as `i + m->num_objects_in_base`). +=== Pseudo-pack order for incremental MIDXs + +The original implementation of multi-pack reachability bitmaps defined +the pseudo-pack order in linkgit:gitformat-pack[5] (see the section +titled "multi-pack-index reverse indexes") roughly as follows: + +____ +In short, a MIDX's pseudo-pack is the de-duplicated concatenation of +objects in packs stored by the MIDX, laid out in pack order, and the +packs arranged in MIDX order (with the preferred pack coming first). +____ + +In the incremental MIDX design, we extend this definition to include +objects from multiple layers of the MIDX chain. The pseudo-pack order +for incremental MIDXs is determined by concatenating the pseudo-pack +ordering for each layer of the MIDX chain in order. Formally two objects +`o1` and `o2` are compared as follows: + +1. If `o1` appears in an earlier layer of the MIDX chain than `o2`, then + `o1` sorts ahead of `o2`. + +2. Otherwise, if `o1` and `o2` appear in the same MIDX layer, and that + MIDX layer has no base, then if one of `pack(o1)` and `pack(o2)` is + preferred and the other is not, then the preferred one sorts ahead of + the non-preferred one. If there is a base layer (i.e. the MIDX layer + is not the first layer in the chain), then if `pack(o1)` appears + earlier in that MIDX layer's pack order, then `o1` sorts ahead of + `o2`. Likewise if `pack(o2)` appears earlier, then the opposite is + true. + +3. Otherwise, `o1` and `o2` appear in the same pack, and thus in the + same MIDX layer. Sort `o1` and `o2` by their offset within their + containing packfile. + +Note that the preferred pack is a property of the MIDX chain, not the +individual layers themselves. Fundamentally we could introduce a +per-layer preferred pack, but this is less relevant now that we can +perform multi-pack reuse across the set of packs in a MIDX. + +=== Reachability bitmaps and incremental MIDXs + +Each layer of an incremental MIDX chain may have its objects (and the +objects from any previous layer in the same MIDX chain) represented in +its own `*.bitmap` file. + +The structure of a `*.bitmap` file belonging to an incremental MIDX +chain is identical to that of a non-incremental MIDX bitmap, or a +classic single-pack bitmap. Since objects are added to the end of the +incremental MIDX's pseudo-pack order (see above), it is possible to +extend a bitmap when appending to the end of a MIDX chain. + +(Note: it is possible likewise to compress a contiguous sequence of MIDX +incremental layers, and their `*.bitmap` files into a single layer and +`*.bitmap`, but this is not yet implemented.) + +The object positions used are global within the pseudo-pack order, so +subsequent layers will have, for example, `m->num_objects_in_base` +number of `0` bits in each of their four type bitmaps. This follows from +the fact that we only write type bitmap entries for objects present in +the layer immediately corresponding to the bitmap). + +Note also that only the bitmap pertaining to the most recent layer in an +incremental MIDX chain is used to store reachability information about +the interesting and uninteresting objects in a reachability query. +Earlier bitmap layers are only used to look up commit and pseudo-merge +bitmaps from that layer, as well as the type-level bitmaps for objects +in that layer. + +To simplify the implementation, type-level bitmaps are iterated +simultaneously, and their results are OR'd together to avoid recursively +calling internal bitmap functions. + Future Work ----------- -- The multi-pack-index allows many packfiles, especially in a context - where repacking is expensive (such as a very large repo), or - unexpected maintenance time is unacceptable (such as a high-demand - build machine). However, the multi-pack-index needs to be rewritten - in full every time. We can extend the format to be incremental, so - writes are fast. By storing a small "tip" multi-pack-index that - points to large "base" MIDX files, we can keep writes fast while - still reducing the number of binary searches required for object - lookups. - - If the multi-pack-index is extended to store a "stable object order" (a function Order(hash) = integer that is constant for a given hash, even as the multi-pack-index is updated) then MIDX bitmaps could be diff --git a/Documentation/technical/sparse-checkout.adoc b/Documentation/technical/sparse-checkout.adoc index d968659354..dc2e763bbe 100644 --- a/Documentation/technical/sparse-checkout.adoc +++ b/Documentation/technical/sparse-checkout.adoc @@ -356,8 +356,6 @@ understanding these differences can be beneficial. The behavior for these commands somewhat depends upon the merge strategy being used: * `ort` behaves as described above - * `recursive` tries to not vivify files unnecessarily, but does sometimes - vivify files without conflicts. * `octopus` and `resolve` will always vivify any file changed in the merge relative to the first parent, which is rather suboptimal. |