git/Documentation
Derrick Stolee 1a445fc60b fetch: add --negotiation-restrict option
The --negotiation-tip option to 'git fetch' and 'git pull' allows users
to specify that they want to focus negotiation on a small set of
references. This is a _restriction_ on the negotiation set, helping to
focus the negotiation when the ref count is high. However, it doesn't
allow for the ability to opportunistically select references beyond that
list.

This subtle detail that this is a 'maximum set' and not a 'minimum set'
is not immediately clear from the option name. This makes it more
complicated to add a new option that provides the complementary behavior
of a minimum set.

For now, create a new synonym option, --negotiation-restrict, that
behaves identically to --negotiation-tip. Update the documentation to
make it clear that this new name is the preferred option, but we keep
the old name for compatibility. Mark --negotiation-tip as an alias of the
new, preferred option.

Update a few warning messages with the new option, but also make them
translatable with the option name inserted by formatting. At least one
of these messages will be reused later for a new option.

Reviewed-by: Matthew John Cheetham <mjcheetham@outlook.com>
Signed-off-by: Derrick Stolee <stolee@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2026-05-20 11:33:23 +09:00
..
RelNotes The 18th batch 2026-03-19 09:54:57 -07:00
config fetch: add --negotiation-restrict option 2026-05-20 11:33:23 +09:00
howto meson: make GIT_HTML_PATH configurable 2025-11-06 09:58:56 -08:00
includes
mergetools doc: check well-formedness of delimited sections 2025-08-11 14:16:03 -07:00
technical Merge branch 'en/xdiff-cleanup-2' 2025-12-05 14:49:56 +09:00
.gitignore
BreakingChanges.adoc refs/files: deprecate writing symrefs as symbolic links 2025-10-15 09:11:08 -07:00
CodingGuidelines Merge branch 'lo/repo-leftover-bits' 2026-03-04 10:53:01 -08:00
DecisionMaking.adoc
Makefile Merge branch 'en/xdiff-cleanup-2' 2025-12-05 14:49:56 +09:00
MyFirstContribution.adoc Merge branch 'sd/doc-my1c-api-config-reference-fix' 2026-02-13 13:39:26 -08:00
MyFirstObjectWalk.adoc
ReviewingGuidelines.adoc
SubmittingPatches Merge branch 'jc/doc-wholesale-replace-before-next' 2026-03-19 09:54:56 -07:00
ToolsForGit.adoc
asciidoc.conf.in doc: convert git-show to synopsis style 2026-02-05 21:14:05 -08:00
asciidoctor-extensions.rb.in
blame-options.adoc doc: blame-options: convert to new doc format 2026-01-09 06:15:31 -08:00
build-docdep.perl
cat-texi.perl
cmd-list.sh
config.adoc Merge branch 'jc/doc-includeif-hasconfig-remote-url-fix' into maint-2.51 2025-10-15 10:29:34 -07:00
date-formats.adoc
diff-algorithm-option.adoc blame: make diff algorithm configurable 2025-11-17 09:31:59 -08:00
diff-context-options.adoc add-patch: add diff.context command line overrides 2025-07-29 08:52:45 -07:00
diff-format.adoc doc: check well-formedness of delimited sections 2025-08-11 14:16:03 -07:00
diff-generate-patch.adoc
diff-options.adoc doc: diff-options.adoc: make *.noprefix split translatable 2026-03-02 08:53:28 -08:00
doc-diff
docbook-xsl.css
docbook.xsl
docinfo-html.in
everyday.adoco
fetch-options.adoc fetch: add --negotiation-restrict option 2026-05-20 11:33:23 +09:00
fix-texi.sh
for-each-ref-options.adoc doc: fix some style issues in git-clone and for-each-ref-options 2026-02-05 21:14:05 -08:00
format-patch-caveats.adoc doc: add caveat about round-tripping format-patch 2026-02-12 14:37:56 -08:00
format-patch-end-of-commit-message.adoc doc: add caveat about round-tripping format-patch 2026-02-12 14:37:56 -08:00
fsck-msgids.adoc builtin/fsck: move generic HEAD check into `refs_fsck()` 2026-01-12 06:55:41 -08:00
generate-mergetool-list.sh
git-add.adoc Documentation: update add --force option + ignore=all config 2026-02-06 09:43:26 -08:00
git-am.adoc Merge branch 'kh/doc-am-xref' 2026-03-02 17:06:52 -08:00
git-annotate.adoc
git-apply.adoc
git-archimport.adoc
git-archive.adoc
git-backfill.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-bisect-lk2009.adoc
git-bisect.adoc bisect: update usage and docs to match each other 2025-10-28 15:41:42 -07:00
git-blame.adoc doc: git-blame: convert to new doc format 2026-01-09 06:15:53 -08:00
git-branch.adoc
git-bugreport.adoc
git-bundle.adoc
git-cat-file.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-check-attr.adoc doc: check for absence of multiple terms in each entry of desc list 2025-08-11 14:16:04 -07:00
git-check-ignore.adoc doc: check for absence of multiple terms in each entry of desc list 2025-08-11 14:16:04 -07:00
git-check-mailmap.adoc
git-check-ref-format.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-checkout-index.adoc
git-checkout.adoc doc: fix asciidoc markup issues in several files 2025-12-20 14:55:43 +09:00
git-cherry-pick.adoc
git-cherry.adoc
git-citool.adoc
git-clean.adoc
git-clone.adoc Merge branch 'cc/lop-filter-auto' 2026-02-25 11:54:17 -08:00
git-column.adoc
git-commit-graph.adoc commit-graph: add new config for changed-paths & recommend it in scalar 2025-10-22 10:40:11 -07:00
git-commit-tree.adoc
git-commit.adoc doc: commit: link to git-status(1) on all format options 2025-11-14 08:56:35 -08:00
git-config.adoc config: make 'git config list --type=<X>' work 2026-02-23 13:23:40 -08:00
git-count-objects.adoc Merge branch 'ds/doc-count-objects-fix' into maint-2.51 2025-10-14 13:40:54 -07:00
git-credential-cache--daemon.adoc
git-credential-cache.adoc
git-credential-store.adoc
git-credential.adoc
git-cvsexportcommit.adoc
git-cvsimport.adoc
git-cvsserver.adoc
git-daemon.adoc
git-describe.adoc
git-diagnose.adoc
git-diff-files.adoc
git-diff-index.adoc
git-diff-pairs.adoc
git-diff-tree.adoc
git-diff.adoc
git-difftool.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-fast-export.adoc
git-fast-import.adoc fast-import: add 'strip-if-invalid' mode to --signed-commits=<mode> 2025-11-26 08:43:44 -08:00
git-fetch-pack.adoc
git-fetch.adoc doc: convert git fetch to synopsis style 2025-11-19 15:00:37 -08:00
git-filter-branch.adoc
git-fmt-merge-msg.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-for-each-ref.adoc Merge branch 'ja/doc-lint-sections-and-synopsis' 2025-08-25 14:22:02 -07:00
git-for-each-repo.adoc
git-format-patch.adoc Merge branch 'mf/format-patch-honor-from-for-cover-letter' 2026-02-27 15:11:54 -08:00
git-fsck-objects.adoc
git-fsck.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-fsmonitor--daemon.adoc
git-gc.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-get-tar-commit-id.adoc
git-grep.adoc
git-gui.adoc
git-hash-object.adoc
git-help.adoc
git-history.adoc Documentation/git-history: document default for "--update-refs=" 2026-02-17 08:37:51 -08:00
git-hook.adoc hook: add -z option to "git hook list" 2026-02-19 13:24:57 -08:00
git-http-backend.adoc
git-http-fetch.adoc doc: check for absence of multiple terms in each entry of desc list 2025-08-11 14:16:04 -07:00
git-http-push.adoc
git-imap-send.adoc docs: explain how to use `git imap-send --list` command to get a list of available folders 2025-07-22 08:49:15 -07:00
git-index-pack.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-init-db.adoc
git-init.adoc breaking-changes: switch default branch to main 2025-09-10 13:34:58 -07:00
git-instaweb.adoc
git-interpret-trailers.adoc doc: interpret-trailers: close all pairs of single quotes 2025-08-22 11:12:27 -07:00
git-last-modified.adoc last-modified: change default max-depth to 0 2026-01-20 14:13:04 -08:00
git-log.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-ls-files.adoc
git-ls-remote.adoc
git-ls-tree.adoc
git-mailinfo.adoc
git-mailsplit.adoc
git-maintenance.adoc maintenance: add 'is-needed' subcommand 2025-11-10 09:28:48 -08:00
git-merge-base.adoc
git-merge-file.adoc merge-file: honor merge.conflictStyle outside of a repository 2026-02-07 17:04:26 -08:00
git-merge-index.adoc
git-merge-one-file.adoc
git-merge-tree.adoc Merge branch 'en/doc-merge-tree-describe-merge-base' 2025-10-10 12:51:46 -07:00
git-merge.adoc
git-mergetool--lib.adoc
git-mergetool.adoc
git-mktag.adoc
git-mktree.adoc
git-multi-pack-index.adoc Merge branch 'kh/doc-markup-fixes' into maint-2.51 2025-10-15 10:29:33 -07:00
git-mv.adoc
git-name-rev.adoc
git-notes.adoc
git-p4.adoc doc: check well-formedness of delimited sections 2025-08-11 14:16:03 -07:00
git-pack-objects.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-pack-redundant.adoc
git-pack-refs.adoc doc: pack-refs: factor out common options 2025-09-19 10:02:56 -07:00
git-patch-id.adoc doc: patch-id: see also git-cherry(1) 2026-02-17 10:49:51 -08:00
git-prune-packed.adoc
git-prune.adoc
git-pull.adoc Merge branch 'je/doc-pull' 2025-12-14 17:04:37 +09:00
git-push.adoc doc: convert git push to synopsis style 2025-11-19 15:00:45 -08:00
git-quiltimport.adoc
git-range-diff.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-read-tree.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-rebase.adoc rebase: support --trailer 2026-03-06 13:02:20 -08:00
git-receive-pack.adoc
git-reflog.adoc builtin/reflog: implement subcommand to write new entries 2025-08-06 07:36:30 -07:00
git-refs.adoc Merge branch 'ms/refs-optimize' 2025-10-02 12:26:12 -07:00
git-remote-ext.adoc
git-remote-fd.adoc
git-remote-helpers.adoco
git-remote.adoc doc: convert git-remote to synopsis style 2025-12-21 11:33:10 +09:00
git-repack.adoc doc: correct minor wording issues 2025-12-20 14:55:43 +09:00
git-replace.adoc
git-replay.adoc Merge branch 'pw/replay-drop-empty' 2026-02-09 12:09:09 -08:00
git-repo.adoc Merge branch 'jt/repo-structure-extrema' 2026-03-16 10:48:14 -07:00
git-request-pull.adoc
git-rerere.adoc rerere: minor documantation update 2026-02-09 11:58:53 -08:00
git-reset.adoc doc: git-reset: clarify `git reset <pathspec>` 2026-01-06 08:10:14 +09:00
git-restore.adoc Merge branch 'lm/add-p-context' 2025-08-04 08:10:33 -07:00
git-rev-list.adoc
git-rev-parse.adoc Merge branch 'bc/sha1-256-interop-01' 2025-10-22 11:38:58 -07:00
git-revert.adoc
git-rm.adoc
git-send-email.adoc Merge branch 'dt/send-email-client-cert' 2026-03-12 10:56:05 -07:00
git-send-pack.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-sh-i18n--envsubst.adoc
git-sh-i18n.adoc
git-sh-setup.adoc
git-shell.adoc
git-shortlog.adoc Merge branch 'kh/doc-shortlog-fix' 2026-02-11 12:29:07 -08:00
git-show-branch.adoc
git-show-index.adoc
git-show-ref.adoc
git-show.adoc doc: convert git-show to synopsis style 2026-02-05 21:14:05 -08:00
git-sparse-checkout.adoc Merge branch 'ds/sparse-checkout-clean' 2025-10-28 10:29:09 -07:00
git-stage.adoc doc: convert git stage to use synopsis block 2025-12-21 11:33:10 +09:00
git-stash.adoc doc: convert git-stash.adoc to synopis style 2025-10-05 16:09:03 -07:00
git-status.adoc doc: convert git-status tables to AsciiDoc format 2025-12-21 11:33:10 +09:00
git-stripspace.adoc
git-submodule.adoc doc: convert git-submodule to synopsis style 2026-02-05 21:14:05 -08:00
git-svn.adoc doc: check well-formedness of delimited sections 2025-08-11 14:16:03 -07:00
git-switch.adoc builtin: unmark git-switch and git-restore as experimental 2025-07-28 14:24:03 -07:00
git-symbolic-ref.adoc
git-tag.adoc Merge branch 'cc/fast-import-strip-signed-tags' 2025-10-28 10:29:09 -07:00
git-tools.adoc
git-unpack-file.adoc
git-unpack-objects.adoc
git-update-index.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-update-ref.adoc Merge branch 'sb/doc-update-ref-markup-fix' 2026-01-23 13:34:35 -08:00
git-update-server-info.adoc
git-upload-archive.adoc
git-upload-pack.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-var.adoc
git-verify-commit.adoc
git-verify-pack.adoc
git-verify-tag.adoc
git-version.adoc
git-web--browse.adoc
git-whatchanged.adoc whatchanged: remove not-even-shorter clause 2025-09-17 13:47:24 -07:00
git-worktree.adoc Merge branch 'sb/doc-worktree-prune-expire-improvement' 2026-02-09 12:09:10 -08:00
git-write-tree.adoc
git.adoc Merge branch 'os/doc-git-custom-commands' 2026-03-16 10:48:14 -07:00
gitattributes.adoc
gitcli.adoc doc: clarify command equivalence comment 2025-11-04 09:25:51 -08:00
gitcore-tutorial.adoc
gitcredentials.adoc Merge branch 'mh/doc-credential-url-prefix' into maint-2.51 2025-10-15 10:29:35 -07:00
gitcvs-migration.adoc
gitdatamodel.adoc doc: remove stray text in Git data model 2025-12-03 00:17:07 -08:00
gitdiffcore.adoc
giteveryday.adoc
gitfaq.adoc Merge branch 'bc/doc-stash-import-export' 2026-01-16 12:40:27 -08:00
gitformat-bundle.adoc
gitformat-chunk.adoc
gitformat-commit-graph.adoc
gitformat-index.adoc
gitformat-loose.adoc rust: add a new binary object map format 2026-02-07 17:41:03 -08:00
gitformat-pack.adoc docs: improve ambiguous areas of pack format documentation 2025-10-09 17:46:14 -07:00
gitformat-signature.adoc
gitglossary.adoc
githooks.adoc doc: join default pre-commit paragraphs 2025-12-08 22:20:14 +09:00
gitignore.adoc doc: document backslash in gitignore patterns 2025-10-29 09:17:21 -07:00
gitk.adoc Merge branch 'js/doc-gitk-history' into maint-2.51 2025-10-14 13:40:53 -07:00
gitmailmap.adoc
gitmodules.adoc Documentation: update add --force option + ignore=all config 2026-02-06 09:43:26 -08:00
gitnamespaces.adoc
gitpacking.adoc
gitprotocol-capabilities.adoc
gitprotocol-common.adoc
gitprotocol-http.adoc doc: clarify server behavior for invalid 'want' lines in HTTP protocol 2025-11-06 09:45:38 -08:00
gitprotocol-pack.adoc doc: gitprotocol-pack: normalize italic formatting 2026-03-02 21:35:05 -08:00
gitprotocol-v2.adoc fetch-pack: wire up and enable auto filter logic 2026-02-17 11:46:41 -08:00
gitremote-helpers.adoc
gitrepository-layout.adoc
gitrevisions.adoc
gitsubmodules.adoc doc: check well-formedness of delimited sections 2025-08-11 14:16:03 -07:00
gittutorial-2.adoc
gittutorial.adoc
gitweb.adoc
gitweb.conf.adoc doc: test linkgit macros for well-formedness 2025-08-11 14:16:03 -07:00
gitworkflows.adoc
glossary-content.adoc doc: add an explanation of Git's data model 2025-11-12 12:21:15 -08:00
i18n.adoc
install-doc-quick.sh
install-webdoc.sh
line-range-format.adoc
line-range-options.adoc
lint-delimited-sections.perl doc: check well-formedness of delimited sections 2025-08-11 14:16:03 -07:00
lint-documentation-style.perl doc lint: check that synopsis manpages have synopsis inlines 2025-08-11 14:16:04 -07:00
lint-fsck-msgids.perl
lint-gitlink.perl lint-gitlink: preemptively ignore all /ifn?def|endif/ macros 2026-01-21 08:26:00 -08:00
lint-man-end-blurb.perl
lint-man-section-order.perl
lint-manpages.sh
manpage-bold-literal.xsl
manpage-normal.xsl
manpage.xsl
merge-options.adoc doc: convert git pull to synopsis style 2025-11-19 15:00:42 -08:00
merge-strategies.adoc
meson.build Merge branch 'pw/meson-doc-mergetool' 2026-03-02 17:06:52 -08:00
object-format-disclaimer.adoc
pack-refs-options.adoc doc: pack-refs: factor out common options 2025-09-19 10:02:56 -07:00
pretty-formats.adoc doc: convert git-show to synopsis style 2026-02-05 21:14:05 -08:00
pretty-options.adoc doc: do not break sentences into "lego" pieces 2025-10-05 16:10:53 -07:00
pull-fetch-param.adoc doc: pull-fetch-param typofix 2025-11-24 10:55:48 -08:00
ref-reachability-filters.adoc
ref-storage-format.adoc doc: fix some style issues in git-clone and for-each-ref-options 2026-02-05 21:14:05 -08:00
rerere-options.adoc doc: rerere-options.adoc: link to git-rerere(1) 2026-02-10 12:27:07 -08:00
rev-list-description.adoc
rev-list-options.adoc Merge branch 'ds/revision-maximal-only' 2026-02-25 11:54:17 -08:00
revisions.adoc
scalar.adoc scalar: document config settings 2025-12-16 09:42:44 +09:00
sequencer.adoc
signoff-option.adoc signoff-option: linkify the reference to gitfaq 2025-12-19 21:51:01 +09:00
texi.xsl
trace2-target-values.adoc
transfer-data-leaks.adoc
urls-remotes.adoc doc: convert git pull to synopsis style 2025-11-19 15:00:42 -08:00
urls.adoc
user-manual.adoc config: drop `git_config()` wrapper 2025-07-23 08:15:18 -07:00