diff --git a/.b4-cover-template b/.b4-cover-template index ab864933b5c846..8168d8a10b3a9e 100644 --- a/.b4-cover-template +++ b/.b4-cover-template @@ -8,4 +8,5 @@ ${diffstat} ${range_diff} --- base-commit: ${base_commit} +change-id: ${change_id} ${prerequisites} diff --git a/Documentation/Makefile b/Documentation/Makefile index 2699f0b24af192..f8dea4b3953250 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -129,6 +129,7 @@ TECH_DOCS += technical/long-running-process-protocol TECH_DOCS += technical/multi-pack-index TECH_DOCS += technical/packfile-uri TECH_DOCS += technical/pack-heuristics +TECH_DOCS += technical/paint-down-to-common TECH_DOCS += technical/parallel-checkout TECH_DOCS += technical/partial-clone TECH_DOCS += technical/platform-support diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc index 4832e5bad59bf1..34bfa2e3a9aaec 100644 --- a/Documentation/MyFirstContribution.adoc +++ b/Documentation/MyFirstContribution.adoc @@ -1477,6 +1477,11 @@ effect which had not occurred to you. It is always okay to ask for clarification if you aren't sure why a change was suggested, or what the reviewer is asking you to do. +When replying to review comments, quote only the parts of the message that are +relevant to your response. It is usually helpful to trim away unrelated context, +such as large portions of the patch that are not being discussed, while keeping +enough quoted text for readers to understand what you are responding to. + Make sure your email client has a plaintext email mode and it is turned on; the Git list rejects HTML email. Please also follow the mailing list etiquette outlined in the diff --git a/Documentation/RelNotes/2.55.0.adoc b/Documentation/RelNotes/2.55.0.adoc index f5643534dcc19c..e7e77a8112385c 100644 --- a/Documentation/RelNotes/2.55.0.adoc +++ b/Documentation/RelNotes/2.55.0.adoc @@ -85,8 +85,8 @@ Performance, Internal Implementation, Development Support etc. * Promisor remote handling has been refactored and fixed in preparation for auto-configuration of advertised remotes. - * Rust support is enabled by default (but still allows opting out) in - some future version of Git. + * Rust support is enabled by default (but still allows opting out); + in Git version 3.0, Rust will become mandatory. * Preparation of the xdiff/ codebase to work with Rust. diff --git a/Documentation/RelNotes/2.56.0.adoc b/Documentation/RelNotes/2.56.0.adoc index b2d2c8a674a7d6..811f74bc7dbcb6 100644 --- a/Documentation/RelNotes/2.56.0.adoc +++ b/Documentation/RelNotes/2.56.0.adoc @@ -43,6 +43,19 @@ UI, Workflows & Features output has been optimized to reserve a column for marks (caret, question mark, or asterisk) only when such marks are actually shown. + * Option parsing with 'git rev-parse --parseopt' and in most 'git' + subcommands has been updated to exit with 0 (instead of 129) when the + help option ('-h' or '--help') is requested directly by the user, + aligning with standard Unix convention. + + * The '[includeIf "condition"]' conditional inclusion facility for + configuration files has been taught to use the location of the + worktree in its condition. + + * The usage string and SYNOPSIS for 'git fast-export' have been + standardized to make them consistent with each other and with other + commands. + Performance, Internal Implementation, Development Support etc. -------------------------------------------------------------- @@ -108,6 +121,91 @@ Performance, Internal Implementation, Development Support etc. the generated header file 'hook-list.h' is built before compiling files in 'builtin_sources' that depend on it. + * The repository discovery and repository configuration phases, which + were previously intertwined in 'setup.c', have been split. Repository + discovery has been updated to populate a 'struct repo_discovery' + without modifying the repository state, which is then taken by + repository configuration to initialize the repository, paving the way + for clean unification of repository configuration. + + * The 'SubmittingPatches' document has been updated to explicitly + describe the expectation for contributors to retract or abandon their + patch series when they are no longer pursuing it. + + * The contributor guide has been updated to advise new contributors to + trim irrelevant quoted text when replying to review comments, matching + the existing advice given to reviewers. + + * The build system has been updated to support building universal macOS + binaries when 'Rust' is enabled, by compiling separate static archives + for each target triple listed in 'RUST_TARGETS' and combining them + using the macOS 'lipo' tool. The 'git-credential-osxkeychain' helper + has been updated to link against '$(RUST_LIB)' when 'Rust' is enabled. + + * The test suite has been updated to use the 'test_grep' helper instead + of bare 'grep' for test assertions, allowing file contents to be + printed on failure for easier debugging. A new 'greplint' linter has + been introduced to detect and prevent new bare 'grep' assertions from + being added to the test suite. + + * The pipelines in 't1410-reflog.sh' have been replaced with the + 'test_stdout_line_count' helper to avoid suppressing the exit code of + 'git' commands, ensuring failures are not hidden from the test suite. + + * The cache-scanning loop in 'next_cache_entry()' has been optimized + to avoid rescanning already-unpacked index entries, preventing a + quadratic performance slow-down when diffing the working tree + against a commit with a pathspec matching early index entries. + + * The global configuration variable 'ignore_case' (representing the + 'core.ignorecase' configuration) has been migrated into 'struct + repo_config_values' to tie it to a specific repository instance. + + * The performance of ref updates and reads using the 'reftable' backend + in the presence of many deletion tombstone records has been optimized + by removing the tombstone suppression flag from the merged iterator + and instead skipping tombstones at higher-level call sites where + iteration bounds are known. + + * Various code paths have been hardened against potential NULL-pointer + dereferences and invalid file descriptor accesses flagged by + Coverity. + + * The in-tree 'b4' cover letter template has been updated to include the + 'change-id' trailer, ensuring that sent tags generated by 'b4' contain + the required tracking information for subsequent runs. + + * 'git receive-pack' has been refactored to use ODB transaction + interfaces instead of directly managing 'tmp_objdir' for staging + incoming objects, bringing it closer to being ODB backend agnostic. + + * The test script 't/t9811-git-p4-label-import.sh' has been + modernized to use 'test_path_is_file' and 'test_path_is_missing' + instead of raw 'test -f' and '! test -f' calls. + + * A redundant strbuf_reset() call in the 'HAVE_GETDELIM' path of + strbuf_getwholeline() has been removed, as getdelim() overwrites the + buffer and the length is updated afterward. + + * The object database enumeration interface odb_for_each_object() has + been taught to accept object filters, allowing the underlying backends + to optimize the traversal by using reachability bitmaps when + available. 'git cat-file --batch-all-objects' has been updated to use + this generic interface, simplifying its code and avoiding direct + access to ODB backend internals. + + * The test script 't/t1100-commit-tree-options.sh' has been modernized + by converting test cases to the modern style (using single quotes and + tab indentation) and moving the creation of the expected file inside + the setup test so it runs under the protection of the test harness. + + * The test script 't/t7614-merge-signoff.sh' has been updated to avoid + suppressing the exit code of 'git' commands in a pipe. + + * The 'git rev-list --no-walk' command has been corrected to restore + pathspec filtering, which was lost when the streaming walk was + refactored. + Fixes since v2.55 ----------------- @@ -215,3 +313,40 @@ Fixes since v2.55 escape sequences that use colon-separated subfields (e.g., for 256-color or true-color codes). (merge 3792b2aea4 mm/sideband-ansi-sgr-colon-fix later to maint). + + * The 'reftable' code has been hardened against corrupted tables by + fixing out-of-bounds writes, out-of-bounds reads, and abort calls + during parsing. + (merge ca93c27328 ps/reftable-hardening later to maint). + + * A description in the release notes for Git 2.55.0 has been + retroactively updated to clarify that Rust support is enabled by + default, but still optional, and will become mandatory in Git 3.0. + (merge 18b2009d14 jc/relnotes-2.55-rust-fix later to maint). + + * The early-exit optimization in 'paint_down_to_common()' has been + gated on the queue being generation-ordered, fixing a bug where + 'git merge-base' (without '--all') could return incorrect results + on repositories with v1 commit graphs and clock skew. + (merge ae68032a8d kk/commit-reach-find-all-fix later to maint). + + * The client-side parser of the server-advertised bundle-URI list has + been updated to drain the remaining response in order to avoid + protocol desynchronization when the server sends a misconfigured list. + Also, the server-side has been taught to omit empty configuration + values instead of sending invalid key-value lines. + (merge 50de1169e4 tc/bundle-uri-empty-fix later to maint). + + * The 'topo_levels' slab was propagated only to the topmost layer of a + split commit-graph chain, causing topological levels for commits in + base layers to be recomputed during incremental writes. This has been + corrected. + + * The stream-based object signature verification path has been + corrected to avoid double-closing the stream on read errors. + (merge cfd52a74a0 ps/odb-stream-double-close-fix later to maint). + + * The '-i' shorthand for the '--init' option, which was accepted by the + 'git submodule update' command until it was broken in a modernization + of the option-parsing code, has been restored. + (merge ff1da37f58 dm/submodule-update-i-shorthand later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index d2d82eb543279d..c269e474e3f2bf 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -123,6 +123,20 @@ of review. top, it gets merged to the 'master' branch and waits to become part of the next major release. +But sometimes things do not work as planned: + +. If a mailing list discussion convinces you that your changes aren't + ideal, please explicitly retract the topic to save the maintainer + time and effort. + +. If you must drop a topic due to shifting priorities, lack of time, + or other commitments, notify the list as a courtesy so others can + take over. Anyone can resurrect the topic later when they have the + capacity to do so. + +. Topics with unaddressed review comments that remain inactive for + four weeks may be discarded by the maintainer. + In the following sections, many techniques and conventions are listed to help your patches get reviewed effectively in such a life cycle. diff --git a/Documentation/config.adoc b/Documentation/config.adoc index 15b1a4d5934758..f67dcd2f8e05dd 100644 --- a/Documentation/config.adoc +++ b/Documentation/config.adoc @@ -146,6 +146,51 @@ refer to linkgit:gitignore[5] for details. For convenience: This is the same as `gitdir` except that matching is done case-insensitively (e.g. on case-insensitive file systems) +`worktree`:: + The data that follows the keyword `worktree` and a colon is used as a + glob pattern. If the working directory of the current worktree matches + the pattern, the include condition is met. ++ +The worktree location is the path where files are checked out (as returned +by `git rev-parse --show-toplevel`). This is different from `gitdir`, which +matches the `.git` directory path. In a linked worktree, the worktree path +is the directory where that worktree's files are located, not the main +repository's `.git` directory. ++ +The pattern uses the same glob syntax as `gitdir` (including `~/`, `./`, +`**/`, and trailing-`/` prefix matching). This condition will never match +in a bare repository (which has no worktree). ++ +Unlike `gitdir`, the `worktree` condition currently matches only the +realpath-resolved worktree location. If the working tree was entered via a +symbolic link, a pattern that uses the symbolic-link spelling may not match; +use the real path instead. ++ +This is useful when you want to apply configuration based on where the +working tree is located on the filesystem. For example, a contributor who +works on the same project both personally and as an employee can use +different `user.name` and `user.email` values depending on which directory +the worktree is checked out under: ++ +---- +[includeIf "worktree:/home/user/work/"] + path = ~/.config/git/work.inc +[includeIf "worktree:/home/user/personal/"] + path = ~/.config/git/personal.inc +---- ++ +While `extensions.worktreeConfig` (see linkgit:git-worktree[1]) also supports +per-worktree configuration, it stores the config inside each repository's +`.git/config.worktree` file and requires running `git config --worktree` +inside each worktree individually. In contrast, `includeIf "worktree:..."` +can be set once in a global or system-level configuration file (e.g. +`~/.config/git/config`) and applies to all repositories at once based on +their worktree location. + +`worktree/i`:: + This is the same as `worktree` except that matching is done + case-insensitively (e.g. on case-insensitive file systems) + `onbranch`:: The data that follows the keyword `onbranch` and a colon is taken to be a pattern with standard globbing wildcards and two additional @@ -244,6 +289,14 @@ Example [includeIf "gitdir:~/to/group/"] path = /path/to/foo.inc +; include if the worktree is at /path/to/project-build +[includeIf "worktree:/path/to/project-build"] + path = build-config.inc + +; include for all worktrees inside /path/to/group +[includeIf "worktree:/path/to/group/"] + path = group-config.inc + ; relative paths are always relative to the including ; file (if the condition is true); their location is not ; affected by the condition @@ -515,6 +568,8 @@ include::config/remotes.adoc[] include::config/repack.adoc[] +include::config/replay.adoc[] + include::config/rerere.adoc[] include::config/revert.adoc[] diff --git a/Documentation/config/advice.adoc b/Documentation/config/advice.adoc index 81f80a92745123..e2a348777837c1 100644 --- a/Documentation/config/advice.adoc +++ b/Documentation/config/advice.adoc @@ -59,6 +59,10 @@ all advice messages. forceDeleteBranch:: Shown when the user tries to delete a not fully merged branch without the force option set. + historyUpdateRefs:: + Shown when `git history squash` refuses because a ref points + into the range being folded, to tell the user about + `--update-refs=head`. ignoredHook:: Shown when a hook is ignored because the hook is not set as executable. diff --git a/Documentation/config/branch.adoc b/Documentation/config/branch.adoc index a4db9fa5c87eab..c2acd89c9936cb 100644 --- a/Documentation/config/branch.adoc +++ b/Documentation/config/branch.adoc @@ -55,6 +55,7 @@ This option defaults to `never`. 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. + The value may be the name of a configured remote or a repository URL. `branch..merge`:: Defines, together with `branch..remote`, the upstream branch @@ -102,3 +103,10 @@ for details). `git branch --edit-description`. Branch description is automatically added to the `format-patch` cover letter or `request-pull` summary. + +`branch..deleteMerged`:: + If set to `false`, branch __ is exempt from + `git branch --delete-merged`. Useful for a topic branch you + intend to develop further after an initial round has been + merged upstream. Defaults to true. Explicit deletion via + `git branch -d` is unaffected. diff --git a/Documentation/config/core.adoc b/Documentation/config/core.adoc index a0ebf03e2eb050..340329edc38143 100644 --- a/Documentation/config/core.adoc +++ b/Documentation/config/core.adoc @@ -589,6 +589,14 @@ core.packedRefsTimeout:: all; -1 means to try indefinitely. Default is 1000 (i.e., retry for 1 second). +core.configLockTimeout:: + The length of time, in milliseconds, to retry when trying to + lock a configuration file for writing. Value 0 means not to + retry at all; -1 means to try indefinitely. Default is 1000 + (i.e., retry for 1 second). This is read from the configuration + that is already on disk before the lock is taken, so it can be + set persistently like any other option. + core.pager:: Text viewer for use by Git commands (e.g., 'less'). The value is meant to be interpreted by the shell. The order of preference diff --git a/Documentation/config/fetch.adoc b/Documentation/config/fetch.adoc index 00435e9a16d9f9..20bf199b447404 100644 --- a/Documentation/config/fetch.adoc +++ b/Documentation/config/fetch.adoc @@ -10,6 +10,20 @@ reference. Defaults to `on-demand`, or to the value of `submodule.recurse` if set. +`fetch.submoduleErrors`:: + Controls how errors from submodule fetches are handled when + `--recurse-submodules` is in effect. When set to `fail` (the default), + any submodule fetch error causes the overall `git fetch` or `git pull` + to exit with a non-zero status. When set to `warn`, submodule fetch + errors are reported to standard error but do not affect the exit + status of the command. This is useful when working in repositories + where some branches reference submodule commits that are not yet + available on the submodule remote, but those commits are not needed + for the currently checked-out branch. ++ +The value of this option can be overridden by the `--submodule-errors` +option of linkgit:git-fetch[1]. + `fetch.fsckObjects`:: If it is set to true, git-fetch-pack will check all fetched objects. See `transfer.fsckObjects` for what's diff --git a/Documentation/config/imap.adoc b/Documentation/config/imap.adoc index cb8f5e2700ae13..6b97776bc3ab47 100644 --- a/Documentation/config/imap.adoc +++ b/Documentation/config/imap.adoc @@ -41,7 +41,7 @@ `imap.authMethod`:: Specify the authentication method for authenticating with the IMAP server. If Git was built with the NO_CURL option, or if your curl version is older - than 7.34.0, or if you're running git-imap-send with the `--no-curl` + than 7.34.0, or if you're running `git-imap-send` with the `--no-curl` option, the only supported methods are `PLAIN`, `CRAM-MD5`, `OAUTHBEARER` and `XOAUTH2`. If this is not set then `git imap-send` uses the basic IMAP plaintext `LOGIN` command. diff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc index 757a7be196ab38..f7dfce69b5f95e 100644 --- a/Documentation/config/log.adoc +++ b/Documentation/config/log.adoc @@ -59,6 +59,10 @@ This is the same as the `--decorate` option of the `git log`. A list of colors, separated by commas, that can be used to draw history lines in `git log --graph`. +`log.graphIndent`:: + If `true`, indent visual roots when rendering the graphs with `--graph`. + Set true by default. It can be overriden with `--[no-]graph-indent`. + `log.showRoot`:: If true, the initial commit will be shown as a big creation event. This is equivalent to a diff against an empty tree. diff --git a/Documentation/config/rebase.adoc b/Documentation/config/rebase.adoc index c6187ab28b2fb7..321ab8b529ca3f 100644 --- a/Documentation/config/rebase.adoc +++ b/Documentation/config/rebase.adoc @@ -62,6 +62,12 @@ instead of: + Defaults to false. +rebase.noEdit:: + When set to true, `git rebase --continue` uses the commit message + without launching $EDITOR, as if `--no-edit` were given. The + `--edit` option to `git rebase --continue` overrides this setting. + Defaults to false. + rebase.rescheduleFailedExec:: Automatically reschedule `exec` commands that failed. This only makes sense in interactive mode (or when an `--exec` option was provided). diff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc index 7d549d2f0e5195..40d1695782affd 100644 --- a/Documentation/config/replay.adoc +++ b/Documentation/config/replay.adoc @@ -1,11 +1,18 @@ replay.refAction:: - Specifies the default mode for handling reference updates in - `git replay`. The value can be: + Specifies the default mode for handling reference updates. + The value can be: + -- - * `update`: Update refs directly using an atomic transaction (default behavior). - * `print`: Output update-ref commands for pipeline use. +//// +These use the first sentences from the description list in git-replay(1). +//// +`update`;; (default) Update refs directly using an atomic transaction. +`print`;; Output update-ref commands for pipeline use. -- + -This setting can be overridden with the `--ref-action` command-line option. -When not configured, `git replay` defaults to `update` mode. +ifdef::git-replay[] +See `--ref-action`. +endif::git-replay[] +ifndef::git-replay[] +See `--ref-action` for linkgit:git-replay[1] for details. +endif::git-replay[] diff --git a/Documentation/config/sendemail.adoc b/Documentation/config/sendemail.adoc index 1d700559b4a4c3..5499f91036b3ec 100644 --- a/Documentation/config/sendemail.adoc +++ b/Documentation/config/sendemail.adoc @@ -1,25 +1,25 @@ -sendemail.identity:: +`sendemail.identity`:: A configuration identity. When given, causes values in the `sendemail.` subsection to take precedence over values in the `sendemail` section. The default identity is the value of `sendemail.identity`. -sendemail.smtpEncryption:: +`sendemail.smtpEncryption`:: See linkgit:git-send-email[1] for description. Note that this setting is not subject to the `identity` mechanism. -sendemail.smtpSSLCertPath:: +`sendemail.smtpSSLCertPath`:: Path to ca-certificates (either a directory or a single file). Set it to an empty string to disable certificate verification. -sendemail.smtpSSLClientCert:: +`sendemail.smtpSSLClientCert`:: Path to the client certificate file to present if requested by the server. This is required when the server is set up to verify client certificates. If the corresponding private key is not included in the file, it must be supplied using `sendemail.smtpSSLClientKey` or the `--smtp-ssl-client-key` option. -sendemail.smtpSSLClientKey:: +`sendemail.smtpSSLClientKey`:: Path to the client private key file that corresponds to the client certificate. To avoid misconfiguration, this configuration must be used in conjunction with `sendemail.smtpSSLClientCert` or the @@ -28,45 +28,45 @@ sendemail.smtpSSLClientKey:: the certificate. Visit https://metacpan.org/pod/IO::Socket::SSL for more details. -sendemail..*:: - Identity-specific versions of the `sendemail.*` parameters +`sendemail..`:: + Identity-specific versions of the `sendemail.` parameters found below, taking precedence over those when this identity is selected, through either the command-line or `sendemail.identity`. -sendemail.multiEdit:: +`sendemail.multiEdit`:: If `true` (default), a single editor instance will be spawned to edit files you have to edit (patches when `--annotate` is used, and the summary when `--compose` is used). If `false`, files will be edited one after the other, spawning a new editor each time. -sendemail.confirm:: +`sendemail.confirm`:: Sets the default for whether to confirm before sending. Must be one of `always`, `never`, `cc`, `compose`, or `auto`. See `--confirm` in the linkgit:git-send-email[1] documentation for the meaning of these values. -sendemail.mailmap:: +`sendemail.mailmap`:: If `true`, makes linkgit:git-send-email[1] assume `--mailmap`, otherwise assume `--no-mailmap`. `False` by default. -sendemail.mailmap.file:: +`sendemail.mailmap.file`:: The location of a linkgit:git-send-email[1] specific augmenting mailmap file. The default mailmap and `mailmap.file` are loaded first. Thus, entries in this file take precedence over entries in the default mailmap locations. See linkgit:gitmailmap[5]. -sendemail.mailmap.blob:: +`sendemail.mailmap.blob`:: Like `sendemail.mailmap.file`, but consider the value as a reference to a blob in the repository. Entries in `sendemail.mailmap.file` take precedence over entries here. See linkgit:gitmailmap[5]. -sendemail.aliasesFile:: +`sendemail.aliasesFile`:: To avoid typing long email addresses, point this to one or more email aliases files. You must also supply `sendemail.aliasFileType`. -sendemail.aliasFileType:: - Format of the file(s) specified in sendemail.aliasesFile. Must be +`sendemail.aliasFileType`:: + Format of the file(s) specified in `sendemail.aliasesFile`. Must be one of `mutt`, `mailrc`, `pine`, `elm`, `gnus`, or `sendmail`. + What an alias file in each format looks like can be found in @@ -75,7 +75,7 @@ differences and limitations from the standard formats are described below: + -- -sendmail;; +`sendmail`;; * Quoted aliases and quoted addresses are not supported: lines that contain a `"` symbol are ignored. * Redirection to a file (`/path/name`) or pipe (`|command`) is not @@ -85,54 +85,54 @@ sendmail;; explicitly unsupported constructs, and any other lines that are not recognized by the parser. -- -sendemail.annotate:: -sendemail.bcc:: -sendemail.cc:: -sendemail.ccCmd:: -sendemail.chainReplyTo:: -sendemail.envelopeSender:: -sendemail.from:: -sendemail.headerCmd:: -sendemail.signedOffByCc:: -sendemail.smtpPass:: -sendemail.suppressCc:: -sendemail.suppressFrom:: -sendemail.to:: -sendemail.toCmd:: -sendemail.smtpDomain:: -sendemail.smtpServer:: -sendemail.smtpServerPort:: -sendemail.smtpServerOption:: -sendemail.smtpUser:: -sendemail.imapSentFolder:: -sendemail.useImapOnly:: -sendemail.thread:: -sendemail.transferEncoding:: -sendemail.validate:: -sendemail.xmailer:: +`sendemail.annotate`:: +`sendemail.bcc`:: +`sendemail.cc`:: +`sendemail.ccCmd`:: +`sendemail.chainReplyTo`:: +`sendemail.envelopeSender`:: +`sendemail.from`:: +`sendemail.headerCmd`:: +`sendemail.signedOffByCc`:: +`sendemail.smtpPass`:: +`sendemail.suppressCc`:: +`sendemail.suppressFrom`:: +`sendemail.to`:: +`sendemail.toCmd`:: +`sendemail.smtpDomain`:: +`sendemail.smtpServer`:: +`sendemail.smtpServerPort`:: +`sendemail.smtpServerOption`:: +`sendemail.smtpUser`:: +`sendemail.imapSentFolder`:: +`sendemail.useImapOnly`:: +`sendemail.thread`:: +`sendemail.transferEncoding`:: +`sendemail.validate`:: +`sendemail.xmailer`:: These configuration variables all provide a default for linkgit:git-send-email[1] command-line options. See its documentation for details. -sendemail.outlookidfix:: +`sendemail.outlookidfix`:: If `true`, makes linkgit:git-send-email[1] assume `--outlook-id-fix`, and if `false` assume `--no-outlook-id-fix`. If not specified, it will behave the same way as if `--outlook-id-fix` is not specified. -sendemail.signedOffCc (deprecated):: +`sendemail.signedOffCc` (deprecated):: Deprecated alias for `sendemail.signedOffByCc`. -sendemail.smtpBatchSize:: +`sendemail.smtpBatchSize`:: Number of messages to be sent per connection, after that a relogin will happen. If the value is `0` or undefined, send all messages in one connection. See also the `--batch-size` option of linkgit:git-send-email[1]. -sendemail.smtpReloginDelay:: +`sendemail.smtpReloginDelay`:: Seconds to wait before reconnecting to the smtp server. See also the `--relogin-delay` option of linkgit:git-send-email[1]. -sendemail.forbidSendmailVariables:: +`sendemail.forbidSendmailVariables`:: To avoid common misconfiguration mistakes, linkgit:git-send-email[1] will abort with a warning if any configuration options for `sendmail` exist. Set this variable to bypass the check. diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc index c8242e24627eef..e605d2867801d0 100644 --- a/Documentation/diff-options.adoc +++ b/Documentation/diff-options.adoc @@ -13,8 +13,8 @@ endif::git-diff[] endif::git-format-patch[] ifdef::git-format-patch[] --p:: ---no-stat:: +`-p`:: +`--no-stat`:: Generate plain patches without any diffstats. endif::git-format-patch[] @@ -893,8 +893,8 @@ endif::git-format-patch[] reverted with `--ita-visible-in-index`. Both options are experimental and could be removed in future. ---max-depth=:: - For each pathspec given on command line, descend at most `` +`--max-depth=`:: + For each pathspec given on command line, descend at most __ levels of directories. A value of `-1` means no limit. Cannot be combined with wildcards in the pathspec. Given a tree containing `foo/bar/baz`, the following list shows the diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc index 035f780e583cee..78525f6848056f 100644 --- a/Documentation/fetch-options.adoc +++ b/Documentation/fetch-options.adoc @@ -294,6 +294,14 @@ ifndef::git-pull[] `--no-recurse-submodules`:: Disable recursive fetching of submodules (this has the same effect as using the `--recurse-submodules=no` option). + +`--submodule-errors=(fail|warn)`:: + Control how errors from submodule fetches are handled when + `--recurse-submodules` is in effect. When set to `fail` (the default), + any submodule fetch error causes the overall `git fetch` to exit with a + non-zero status. When set to `warn`, submodule fetch errors are reported + to standard error but do not affect the exit status of the command. Can + also be configured via `fetch.submoduleErrors`. See linkgit:git-config[1]. endif::git-pull[] `--set-upstream`:: diff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc index d2115b29905f41..aabddd42ca4d31 100644 --- a/Documentation/git-bisect.adoc +++ b/Documentation/git-bisect.adoc @@ -10,7 +10,7 @@ SYNOPSIS -------- [synopsis] git bisect start [--term-(bad|new)= --term-(good|old)=] - [--no-checkout] [--first-parent] [ [...]] [--] [...] + [--no-checkout] [--first-parent] [--reset-when-found[=]] [ [...]] [--] [...] git bisect (bad|new|) [] git bisect (good|old|) [...] git bisect terms [--term-(good|old) | --term-(bad|new)] @@ -20,7 +20,7 @@ git bisect reset [] git bisect (visualize|view) git bisect replay git bisect log -git bisect run [...] +git bisect run [--reset-when-found[=]] [...] git bisect help DESCRIPTION @@ -385,6 +385,16 @@ ignored. This option is particularly useful in avoiding false positives when a merged branch contained broken or non-buildable commits, but the merge itself was OK. +`--reset-when-found[=]`:: + Once the first bad commit is found, report it and clean up the + bisection state. `` may be `original` to return to the commit + checked out before `git bisect start`, or `found` to leave the first + bad commit checked out. If `` is omitted, it defaults to + `original`. ++ +This option may be given to `git bisect start` or to `git bisect run`. It +cannot be used for a bisection started with `--no-checkout`. + EXAMPLES -------- diff --git a/Documentation/git-branch.adoc b/Documentation/git-branch.adoc index c0afddc424d610..51dda151142c66 100644 --- a/Documentation/git-branch.adoc +++ b/Documentation/git-branch.adoc @@ -13,6 +13,7 @@ git branch [--color[=] | --no-color] [--show-current] [--column[=] | --no-column] [--sort=] [--merged []] [--no-merged []] [--contains []] [--no-contains []] + [(--forked )...] [--points-at ] [--format=] [(-r|--remotes) | (-a|--all)] [--list] [...] @@ -24,6 +25,7 @@ git branch (-m|-M) [] git branch (-c|-C) [] git branch (-d|-D) [-r] ... git branch --edit-description [] +git branch [--dry-run] (--delete-merged )... [...] DESCRIPTION ----------- @@ -51,7 +53,8 @@ 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 __ argument is missing it defaults to `HEAD` (i.e. the tip of the current -branch). +branch). With `--forked`, only branches whose configured upstream matches +the given branch or pattern will be listed. The command's second form creates a new branch head named __ which points to the current `HEAD`, or __ if given. As a @@ -199,6 +202,42 @@ This option is only applicable in non-verbose mode. Print the name of the current branch. In detached `HEAD` state, nothing is printed. +`--delete-merged `:: + Delete local branches whose configured upstream matches + __, but only when their tip is reachable from that + upstream. In other words, the work on the branch has already + landed on the upstream it tracks, so the local copy is no longer + needed. The option can be repeated to widen the upstream match. + Optional __ arguments limit which local branches are + considered, e.g. `git branch --delete-merged 'origin/*' + 'topic-*'`. ++ +A branch is not deleted when: ++ +-- +* its configured upstream ref no longer exists, +* it is checked out in any worktree, +* pushing it by name to the remote configured by + `branch..remote` would update its upstream, so it cannot be + distinguished from a branch that just looks "fully merged" right + after a pull, or +* `branch..deleteMerged` is set to `false`. +-- ++ +A branch whose work has not yet been merged into its upstream is +silently skipped. Delete it with `git branch -D` if you want to +remove it anyway. ++ +A branch that a surviving branch depends on through a chain of local +upstreams is kept, so a branch is never deleted out from under stacked +work. + +`--dry-run`:: + With `--delete-merged`, print which branches would be + deleted and exit without touching any ref. Useful for + sanity-checking a wide pattern like `'origin/*'` before + committing to the deletion. + `-v`:: `-vv`:: `--verbose`:: @@ -311,6 +350,14 @@ superproject's "origin/main", but tracks the submodule's "origin/main". Only list branches whose tips are not reachable from __ (`HEAD` if not specified). Implies `--list`. +`--forked `:: + Only list branches whose configured upstream matches + __. The argument can be a ref (e.g. `origin/main`, + `master`), a remote name like `origin` for the branch its + `origin/HEAD` points at, or a shell-style glob (e.g. + `'origin/*'`). The option can be repeated to widen the + filter. Implies `--list`. + `--points-at `:: Only list branches of __. diff --git a/Documentation/git-cat-file.adoc b/Documentation/git-cat-file.adoc index 86b9181599317e..b9cd958e1172ce 100644 --- a/Documentation/git-cat-file.adoc +++ b/Documentation/git-cat-file.adoc @@ -169,6 +169,13 @@ info :: Print object info for object reference ``. This corresponds to the output of `--batch-check`. +remote-object-info ...:: + Print object info for object references `` at specified + `` without downloading objects from the remote. + Raise an error when the `object-info` capability is not supported by the remote. + Raise an error when no object references are provided. + This command may be combined with `--buffer`. + flush:: Used with `--buffer` to execute all preceding commands that were issued since the beginning or since the last flush was issued. When `--buffer` @@ -301,7 +308,8 @@ one per line, and print information based on the command given. With `--batch-command`, the `info` command followed by an object will print information about the object the same way `--batch-check` would, and the `contents` command followed by an object prints contents in the same way -`--batch` would. +`--batch` would. The `remote-object-info` command followed by a remote and +objects IDs prints object info from the remote without downloading the objects. You can specify the information shown for each object by using a custom ``. The `` is copied literally to stdout for each @@ -330,7 +338,7 @@ newline. The available atoms are: `deltabase`:: If the object is stored as a delta on-disk, this expands to the full hex representation of the delta base object name. - Otherwise, expands to the null OID (all zeroes). See `CAVEATS` + Otherwise, expands to the null OID (all zeroes). See `CAVEATS` section below. `rest`:: @@ -340,8 +348,14 @@ newline. The available atoms are: after that first run of whitespace (i.e., the "rest" of the line) are output in place of the `%(rest)` atom. +The command `remote-object-info` only supports the `%(objectname)` and +`%(objectsize)` placeholders. See `CAVEATS` below for more information. + If no format is specified, the default format is `%(objectname) -%(objecttype) %(objectsize)`. +%(objecttype) %(objectsize)`, except for `remote-object-info` commands which +use `%(objectname) %(objectsize)` because "%(objecttype)" is not supported yet. +WARNING: When "%(objecttype)" is supported, the default format WILL be unified, +so DO NOT RELY on the current default format to stay the same!!! If `--batch` is specified, or if `--batch-command` is used with the `contents` command, the object information is followed by the object contents (consisting @@ -438,6 +452,10 @@ scripting purposes. CAVEATS ------- +Note that only `%(objectname)` and `%(objectsize)` are currently +supported by the `remote-object-info` command. Using any other placeholder in +the format string will return an empty string in its position. + Note that the sizes of objects on disk are reported accurately, but care should be taken in drawing conclusions about which refs or objects are responsible for disk usage. The size of a packed non-delta object may be diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index a8b3b8c2e238bf..20b6cae60e57fc 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -158,11 +158,26 @@ of it"). resets __ to the start point instead of failing. `-t`:: -`--track[=(direct|inherit)]`:: +`--track[=(direct|inherit|fetch)[,...]]`:: When creating a new branch, set up "upstream" configuration. See `--track` in linkgit:git-branch[1] for details. As a convenience, --track without -b implies branch creation. + +The argument is a comma-separated list. `direct` (the default) and +`inherit` select the tracking mode and are mutually exclusive. Adding +`fetch` requests that the remote be fetched before __ is +resolved, so the new branch starts from a fresh tip: when +__ is in _/_ form, only that branch is +updated; when __ is a bare __ (e.g. `origin`), the +branch named by _/HEAD_ is updated, and the checkout fails +with a hint to configure that symref if it is not set. The checkout +also fails if no configured remote's fetch refspec maps to +__, or if more than one does (in which case the `fetch` +cannot be unambiguously routed). If the fetch itself fails and the +corresponding remote-tracking ref already exists, a warning is printed +and the checkout proceeds from the existing tip; otherwise the checkout +is aborted. ++ If no `-b` option is given, the name of the new branch will be derived from the remote-tracking branch, by looking at the local part of the refspec configured for the corresponding remote, and then stripping diff --git a/Documentation/git-commit.adoc b/Documentation/git-commit.adoc index 8329c1034b9b30..98c50a3be5c81c 100644 --- a/Documentation/git-commit.adoc +++ b/Documentation/git-commit.adoc @@ -102,21 +102,23 @@ include::diff-context-options.adoc[] + The commit created by plain `--fixup=` has a title composed of "fixup!" followed by the title of __, -and is recognized specially by `git rebase --autosquash`. The `-m` -option may be used to supplement the log message of the created -commit, but the additional commentary will be thrown away once the -"fixup!" commit is squashed into __ by +and is recognized specially by `git rebase --autosquash`. The `-m`, +`-F`, `-C`, or `-c` option may be used to supplement the log message +of the created commit, but the additional commentary will be thrown +away once the "fixup!" commit is squashed into __ by `git rebase --autosquash`. + The commit created by `--fixup=amend:` is similar but its title is instead prefixed with "amend!". The log message of __ is copied into the log message of the "amend!" commit and -opened in an editor so it can be refined. When `git rebase ---autosquash` squashes the "amend!" commit into __, the -log message of __ is replaced by the refined log message -from the "amend!" commit. It is an error for the "amend!" commit's -log message to be empty unless `--allow-empty-message` is -specified. +opened in an editor so it can be refined. The replacement message may +also be supplied directly using `-m`, `-F`, or `-C`, bypassing the +need to open an editor, or using `-c` to open the editor pre-populated +with the referenced commit's message. When `git rebase +--autosquash` squashes the "amend!" commit into __, the log +message of __ is replaced by the refined log message from the +"amend!" commit. It is an error for the "amend!" commit's log message +to be empty unless `--allow-empty-message` is specified. + `--fixup=reword:` is shorthand for `--fixup=amend: --only`. It creates an "amend!" commit with only a log message diff --git a/Documentation/git-fast-export.adoc b/Documentation/git-fast-export.adoc index 297b57bb2efdc2..719aeca244d534 100644 --- a/Documentation/git-fast-export.adoc +++ b/Documentation/git-fast-export.adoc @@ -9,7 +9,7 @@ git-fast-export - Git data exporter SYNOPSIS -------- [verse] -'git fast-export' [] | 'git fast-import' +'git fast-export' [] [] [[--] ...] DESCRIPTION ----------- diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc index d68bc52b7e9cd7..7c5900e048cefb 100644 --- a/Documentation/git-fast-import.adoc +++ b/Documentation/git-fast-import.adoc @@ -9,7 +9,7 @@ git-fast-import - Backend for fast Git data importers SYNOPSIS -------- [verse] -frontend | 'git fast-import' [] +'git fast-import' [] DESCRIPTION ----------- diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc index f7905c0f7c0322..5eccb2cf600137 100644 --- a/Documentation/git-format-patch.adoc +++ b/Documentation/git-format-patch.adoc @@ -8,8 +8,8 @@ git-format-patch - Prepare patches for e-mail submission SYNOPSIS -------- -[verse] -'git format-patch' [-k] [(-o|--output-directory) | --stdout] +[synopsis] +git format-patch [-k] [(-o|--output-directory) | --stdout] [--no-thread | --thread[=