diff options
Diffstat (limited to 'Documentation')
33 files changed, 714 insertions, 78 deletions
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 35b9130aa3..427274df4d 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -23,6 +23,42 @@ useful additional context: - `Documentation/SubmittingPatches` - `Documentation/howto/new-command.txt` +[[getting-help]] +=== Getting Help + +If you get stuck, you can seek help in the following places. + +==== git@vger.kernel.org + +This is the main Git project mailing list where code reviews, version +announcements, design discussions, and more take place. Those interested in +contributing are welcome to post questions here. The Git list requires +plain-text-only emails and prefers inline and bottom-posting when replying to +mail; you will be CC'd in all replies to you. Optionally, you can subscribe to +the list by sending an email to majordomo@vger.kernel.org with "subscribe git" +in the body. The https://lore.kernel.org/git[archive] of this mailing list is +available to view in a browser. + +==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com] + +This mailing list is targeted to new contributors and was created as a place to +post questions and receive answers outside of the public eye of the main list. +Veteran contributors who are especially interested in helping mentor newcomers +are present on the list. In order to avoid search indexers, group membership is +required to view messages; anyone can join and no approval is required. + +==== https://webchat.freenode.net/#git-devel[#git-devel] on Freenode + +This IRC channel is for conversations between Git contributors. If someone is +currently online and knows the answer to your question, you can receive help +in real time. Otherwise, you can read the +https://colabti.org/irclogger/irclogger_logs/git-devel[scrollback] to see +whether someone answered you. IRC does not allow offline private messaging, so +if you try to private message someone and then log out of IRC, they cannot +respond to you. It's better to ask your questions in the channel so that you +can be answered if you disconnect and so that others can learn from the +conversation. + [[getting-started]] == Getting Started diff --git a/Documentation/RelNotes/2.25.1.txt b/Documentation/RelNotes/2.25.1.txt new file mode 100644 index 0000000000..cd869b02bb --- /dev/null +++ b/Documentation/RelNotes/2.25.1.txt @@ -0,0 +1,55 @@ +Git 2.25.1 Release Notes +======================== + +Fixes since v2.25 +----------------- + + * "git commit" gives output similar to "git status" when there is + nothing to commit, but without honoring the advise.statusHints + configuration variable, which has been corrected. + + * has_object_file() said "no" given an object registered to the + system via pretend_object_file(), making it inconsistent with + read_object_file(), causing lazy fetch to attempt fetching an + empty tree from promisor remotes. + + * The code that tries to skip over the entries for the paths in a + single directory using the cache-tree was not careful enough + against corrupt index file. + + * Complete an update to tutorial that encourages "git switch" over + "git checkout" that was done only half-way. + + * Reduce unnecessary round-trip when running "ls-remote" over the + stateless RPC mechanism. + + * "git restore --staged" did not correctly update the cache-tree + structure, resulting in bogus trees to be written afterwards, which + has been corrected. + + * The code recently added to move to the entry beyond the ones in the + same directory in the index in the sparse-cone mode did not count + the number of entries to skip over incorrectly, which has been + corrected. + + * Work around test breakages caused by custom regex engine used in + libasan, when address sanitizer is used with more recent versions + of gcc and clang. + + * "git fetch --refmap=" option has got a better documentation. + + * Corner case bugs in "git clean" that stems from a (necessarily for + performance reasons) awkward calling convention in the directory + enumeration API has been corrected. + + * "git grep --no-index" should not get affected by the contents of + the .gitmodules file but when "--recurse-submodules" is given or + the "submodule.recurse" variable is set, it did. Now these + settings are ignored in the "--no-index" mode. + + * Technical details of the bundle format has been documented. + + * Unhelpful warning messages during documentation build have been + squelched. + +Also contains various documentation updates, code clean-ups and minor fixups. diff --git a/Documentation/RelNotes/2.26.0.txt b/Documentation/RelNotes/2.26.0.txt new file mode 100644 index 0000000000..7305565d94 --- /dev/null +++ b/Documentation/RelNotes/2.26.0.txt @@ -0,0 +1,240 @@ +Git 2.26 Release Notes +====================== + +Updates since v2.25 +------------------- + +UI, Workflows & Features + + * Sample credential helper for using .netrc has been updated to work + out of the box. + + * gpg.minTrustLevel configuration variable has been introduced to + tell various signature verification codepaths the required minimum + trust level. + + * The command line completion (in contrib/) learned to complete + subcommands and arguments to "git worktree". + + * Disambiguation logic to tell revisions and pathspec apart has been + tweaked so that backslash-escaped glob special characters do not + count in the "wildcards are pathspec" rule. + + * One effect of specifying where the GIT_DIR is (either with the + environment variable, or with the "git --git-dir=<where> cmd" + option) is to disable the repository discovery. This has been + placed a bit more stress in the documentation, as new users often + get confused. + + * Two help messages given when "git add" notices the user gave it + nothing to add have been updated to use advise() API. + + * A new version of fsmonitor-watchman hook has been introduced, to + avoid races. + + * "git config" learned to show in which "scope", in addition to in + which file, each config setting comes from. + + * The basic 7 colors learned the brighter counterparts + (e.g. "brightred"). + + +Performance, Internal Implementation, Development Support etc. + + * Tell .editorconfig that in this project, *.txt files are indented + with tabs. + + * The test-lint machinery knew to check "VAR=VAL shell_function" + construct, but did not check "VAR= shell_funciton", which has been + corrected. + + * Replace "git config --bool" calls with "git config --type=bool" in + sample templates. + + * The effort to move "git-add--interactive" to C continues. + + * Improve error message generation for "git submodule add". + + * Preparation of test scripts for the day when the object names will + use SHA-256 continues. + + * Warn programmers about pretend_object_file() that allows the code + to tentatively use in-core objects. + + * The way "git pack-objects" reuses objects stored in existing pack + to generate its result has been improved. + + * The transport protocol version 2 becomes the default one. + + * Traditionally, we avoided threaded grep while searching in objects + (as opposed to files in the working tree) as accesses to the object + layer is not thread-safe. This limitation is getting lifted. + + * "git rebase -i" (and friends) used to unnecessarily check out the + tip of the branch to be rebased, which has been corrected. + + * A low-level API function get_oid(), that accepts various ways to + name an object, used to issue end-user facing error messages + without l10n, which has been updated to be translatable. + + * Unneeded connectivity check is now disabled in a partial clone when + fetching into it. + + * Some rough edges in the sparse-checkout feature, especially around + the cone mode, have been cleaned up. + + * The diff-* plumbing family of subcommands now pay attention to the + diff.wsErrorHighlight configuration, which has been ignored before; + this allows "git add -p" to also show the whitespace problems to + the end user. + + * Some codepaths were given a repository instance as a parameter to + work in the repository, but passed the_repository instance to its + callees, which has been cleaned up (somewhat). + + * Memory footprint and performance of "git name-rev" has been + improved. + + +Fixes since v2.25 +----------------- + + * "git commit" gives output similar to "git status" when there is + nothing to commit, but without honoring the advise.statusHints + configuration variable, which has been corrected. + + * has_object_file() said "no" given an object registered to the + system via pretend_object_file(), making it inconsistent with + read_object_file(), causing lazy fetch to attempt fetching an + empty tree from promisor remotes. + + * Complete an update to tutorial that encourages "git switch" over + "git checkout" that was done only half-way. + + * C pedantry ;-) fix. + + * The code that tries to skip over the entries for the paths in a + single directory using the cache-tree was not careful enough + against corrupt index file. + + * Reduce unnecessary round-trip when running "ls-remote" over the + stateless RPC mechanism. + + * "git restore --staged" did not correctly update the cache-tree + structure, resulting in bogus trees to be written afterwards, which + has been corrected. + + * The code recently added to move to the entry beyond the ones in the + same directory in the index in the sparse-cone mode did not count + the number of entries to skip over incorrectly, which has been + corrected. + + * Rendering by "git log --graph" of ancestry lines leading to a merge + commit were made suboptimal to waste vertical space a bit with a + recent update, which has been corrected. + + * Work around test breakages caused by custom regex engine used in + libasan, when address sanitizer is used with more recent versions + of gcc and clang. + + * Minor bugfixes to "git add -i" that has recently been rewritten in C. + (merge 849e43cc18 js/builtin-add-i-cmds later to maint). + + * "git fetch --refmap=" option has got a better documentation. + + * "git checkout X" did not correctly fail when X is not a local + branch but could name more than one remote-tracking branches + (i.e. to be dwimmed as the starting point to create a corresponding + local branch), which has been corrected. + (merge fa74180d08 am/checkout-file-and-ref-ref-ambiguity later to maint). + + * Corner case bugs in "git clean" that stems from a (necessarily for + performance reasons) awkward calling convention in the directory + enumeration API has been corrected. + + * A fetch that is told to recursively fetch updates in submodules + inevitably produces reams of output, and it becomes hard to spot + error messages. The command has been taught to enumerate + submodules that had errors at the end of the operation. + (merge 0222540827 es/fetch-show-failed-submodules-atend later to maint). + + * The "--recurse-submodules" option of various subcommands did not + work well when run in an alternate worktree, which has been + corrected. + (merge a9472afb63 pb/recurse-submodule-in-worktree-fix later to maint). + + * Futureproofing a test not to depend on the current implementation + detail. + + * Running "git rm" on a submodule failed unnecessarily when + .gitmodules is only cache-dirty, which has been corrected. + (merge 7edee32985 dt/submodule-rm-with-stale-cache later to maint). + + * C pedantry ;-) fix. + (merge cf82bff73f jk/clang-sanitizer-fixes later to maint). + + * "git grep --no-index" should not get affected by the contents of + the .gitmodules file but when "--recurse-submodules" is given or + the "submodule.recurse" variable is set, it did. Now these + settings are ignored in the "--no-index" mode. + + * Technical details of the bundle format has been documented. + + * Unhelpful warning messages during documentation build have been squelched. + + * "git rebase -i" identifies existing commits in its todo file with + their abbreviated object name, which could become ambigous as it + goes to create new commits, and has a mechanism to avoid ambiguity + in the main part of its execution. A few other cases however were + not covered by the protection against ambiguity, which has been + corrected. + (merge 26027625dd js/rebase-i-with-colliding-hash later to maint). + + * Allow the rebase.missingCommitsCheck configuration to kick in when + "rebase --edit-todo" and "rebase --continue" restarts the procedure. + (merge 5a5445d878 ag/edit-todo-drop-check later to maint). + + * The way "git submodule status" reports an initialized but not yet + populated submodule has not been reimplemented correctly when a + part of the "git submodule" command was rewritten in C, which has + been corrected. + (merge f38c92452d pk/status-of-uncloned-submodule later to maint). + + * The code to automatically shrink the fan-out in the notes tree had + an off-by-one bug, which has been killed. + (merge dbc27477ff jh/notes-fanout-fix later to maint). + + * The index-pack code now diagnoses a bad input packstream that + records the same object twice when it is used as delta base; the + code used to declare a software bug when encountering such an + input, but it is an input error. + (merge a21781011f jk/index-pack-dupfix later to maint). + + * The code to compute the commit-graph has been taught to use a more + robust way to tell if two object directories refer to the same + thing. + (merge a7df60cac8 tb/commit-graph-object-dir later to maint). + + * "git remote rename X Y" needs to adjust configuration variables + (e.g. branch.<name>.remote) whose value used to be X to Y. + branch.<name>.pushRemote is now also updated. + + * Other code cleanup, docfix, build fix, etc. + (merge 26f924d50e en/simplify-check-updates-in-unpack-trees later to maint). + (merge d0d0a357a1 am/update-pathspec-f-f-tests later to maint). + (merge f94f7bd00d am/test-pathspec-f-f-error-cases later to maint). + (merge c513a958b6 ss/t6025-modernize later to maint). + (merge b441717256 dl/test-must-fail-fixes later to maint). + (merge d031049da3 mt/sparse-checkout-doc-update later to maint). + (merge 145136a95a jc/skip-prefix later to maint). + (merge 5290d45134 jk/alloc-cleanups later to maint). + (merge 7a9f8ca805 rs/parse-options-concat-dup later to maint). + (merge 517b60564e rs/strbuf-insertstr later to maint). + (merge f696a2b1c8 jk/mailinfo-cleanup later to maint). + (merge 076ee3e8a2 js/test-write-junit-xml-fix later to maint). + (merge de26f02db1 js/test-avoid-pipe later to maint). + (merge bfe2bbb47f js/test-unc-fetch later to maint). + (merge 08809c09aa js/mingw-open-in-gdb later to maint). + (merge cc4f2eb828 jk/doc-credential-helper later to maint). + (merge e0020b2f82 es/outside-repo-errmsg-hints later to maint). + (merge a2dc43414c es/doc-mentoring later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index 83e7bba872..08b13ba72b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -263,7 +263,9 @@ color:: + The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan` and `white`. The first color given is the -foreground; the second is the background. +foreground; the second is the background. All the basic colors except +`normal` have a bright variant that can be speficied by prefixing the +color with `bright`, like `brightred`. + Colors may also be given as numbers between 0 and 255; these use ANSI 256-color mode (but note that not all terminals may support this). If diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index 4be93f8ad9..bdd37c3eaa 100644 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@ -110,4 +110,10 @@ advice.*:: submoduleAlternateErrorStrategyDie:: Advice shown when a submodule.alternateErrorStrategy option configured to "die" causes a fatal error. + addIgnoredFile:: + Advice shown if a user attempts to add an ignored file to + the index. + addEmptyPathspec:: + Advice shown if a user runs the add command without providing + the pathspec parameter. -- diff --git a/Documentation/config/branch.txt b/Documentation/config/branch.txt index a592d522a7..cc5f3249fc 100644 --- a/Documentation/config/branch.txt +++ b/Documentation/config/branch.txt @@ -81,15 +81,16 @@ branch.<name>.rebase:: "git pull" is run. See "pull.rebase" for doing this in a non branch-specific manner. + -When `merges`, 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 `preserve` (deprecated in favor of `merges`), also pass +When `preserve` (or just 'p', deprecated in favor of `merges`), also pass `--preserve-merges` along to 'git rebase' so that locally committed merge commits will not be flattened by running 'git pull'. + -When the value is `interactive`, the rebase is run in interactive mode. +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] diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index 9e440b160d..74619a9c03 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -68,6 +68,17 @@ core.fsmonitor:: avoiding unnecessary processing of files that have not changed. See the "fsmonitor-watchman" section of linkgit:githooks[5]. +core.fsmonitorHookVersion:: + Sets the version of hook that is to be used when calling fsmonitor. + There are currently versions 1 and 2. When this is not set, + version 2 will be tried first and if it fails then version 1 + will be tried. Version 1 uses a timestamp as input to determine + which files have changes since that time but some monitors + like watchman have race conditions when used with a timestamp. + Version 2 uses an opaque string so that the monitor can return + something that can be used to determine what files have changed + without race conditions. + core.trustctime:: If false, the ctime differences between the index and the working tree are ignored; useful when the inode change time diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt index cce2c89245..d94025cb36 100644 --- a/Documentation/config/gpg.txt +++ b/Documentation/config/gpg.txt @@ -18,3 +18,18 @@ gpg.<format>.program:: chose. (see `gpg.program` and `gpg.format`) `gpg.program` can still be used as a legacy synonym for `gpg.openpgp.program`. The default value for `gpg.x509.program` is "gpgsm". + +gpg.minTrustLevel:: + Specifies a minimum trust level for signature verification. If + this option is unset, then signature verification for merge + operations require a key with at least `marginal` trust. Other + operations that perform signature verification require a key + with at least `undefined` trust. Setting this option overrides + the required trust-level for all operations. Supported values, + in increasing order of significance: ++ +* `undefined` +* `never` +* `marginal` +* `fully` +* `ultimate` diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt index 5a32f5b0a5..e806033aab 100644 --- a/Documentation/config/http.txt +++ b/Documentation/config/http.txt @@ -71,7 +71,7 @@ http.saveCookies:: http.version:: Use the specified HTTP protocol version when communicating with a server. If you want to force the default. The available and default version depend - on libcurl. Actually the possible values of + on libcurl. Currently the possible values of this option are: - HTTP/2 @@ -84,7 +84,7 @@ http.sslVersion:: particular configuration of the crypto library in use. Internally this sets the 'CURLOPT_SSL_VERSION' option; see the libcurl documentation for more details on the format of this option and - for the ssl version supported. Actually the possible values of + for the ssl version supported. Currently the possible values of this option are: - sslv2 @@ -199,6 +199,14 @@ http.postBuffer:: Transfer-Encoding: chunked is used to avoid creating a massive pack file locally. Default is 1 MiB, which is sufficient for most requests. ++ +Note that raising this limit is only effective for disabling chunked +transfer encoding and therefore should be used only where the remote +server or a proxy only supports HTTP/1.0 or is noncompliant with the +HTTP standard. Raising this is not, in general, an effective solution +for most push problems, but can increase memory consumption +significantly since the entire buffer is allocated even for small +pushes. http.lowSpeedLimit, http.lowSpeedTime:: If the HTTP transfer speed is less than 'http.lowSpeedLimit' diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt index 1d66f0c992..0dac580581 100644 --- a/Documentation/config/pack.txt +++ b/Documentation/config/pack.txt @@ -27,6 +27,13 @@ Note that changing the compression level will not automatically recompress all existing objects. You can force recompression by passing the -F option to linkgit:git-repack[1]. +pack.allowPackReuse:: + When true, and when reachability bitmaps are enabled, + pack-objects will try to send parts of the bitmapped packfile + verbatim. This can reduce memory and CPU usage to serve fetches, + but might result in sending a slightly larger pack. Defaults to + true. + pack.island:: An extended regular expression configuring a set of delta islands. See "DELTA ISLANDS" in linkgit:git-pack-objects[1] diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt index bfccc07491..756591d77b 100644 --- a/Documentation/config/protocol.txt +++ b/Documentation/config/protocol.txt @@ -45,11 +45,10 @@ The protocol names currently used by git are: -- protocol.version:: - Experimental. If set, clients will attempt to communicate with a - server using the specified protocol version. If unset, no - attempt will be made by the client to communicate using a - particular protocol version, this results in protocol version 0 - being used. + If set, clients will attempt to communicate with a server + using the specified protocol version. If the server does + not support it, communication falls back to version 0. + If unset, the default is `2`. Supported versions: + -- diff --git a/Documentation/config/pull.txt b/Documentation/config/pull.txt index b87cab31b3..5404830609 100644 --- a/Documentation/config/pull.txt +++ b/Documentation/config/pull.txt @@ -14,15 +14,16 @@ pull.rebase:: pull" is run. See "branch.<name>.rebase" for setting this on a per-branch basis. + -When `merges`, 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 `preserve` (deprecated in favor of `merges`), also pass +When `preserve` (or just 'p', deprecated in favor of `merges`), also pass `--preserve-merges` along to 'git rebase' so that locally committed merge commits will not be flattened by running 'git pull'. + -When the value is `interactive`, the rebase is run in interactive mode. +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] diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt index 0a0e000569..0a7aa322a9 100644 --- a/Documentation/config/push.txt +++ b/Documentation/config/push.txt @@ -1,6 +1,7 @@ push.default:: Defines the action `git push` should take if no refspec is - explicitly given. Different values are well-suited for + given (whether from the command-line, config, or elsewhere). + Different values are well-suited for specific workflows; for instance, in a purely central workflow (i.e. the fetch source is equal to the push destination), `upstream` is probably what you want. Possible values are: @@ -8,7 +9,7 @@ push.default:: -- * `nothing` - do not push anything (error out) unless a refspec is - explicitly given. This is primarily meant for people who want to + given. This is primarily meant for people who want to avoid mistakes by always being explicit. * `current` - push the current branch to update a branch with the same @@ -79,7 +80,7 @@ higher priority configuration file (e.g. `.git/config` in a repository) to clear the values inherited from a lower priority configuration files (e.g. `$HOME/.gitconfig`). + --- +---- Example: @@ -96,7 +97,7 @@ repo/.git/config This will result in only b (a and c are cleared). --- +---- push.recurseSubmodules:: Make sure all submodule commits used by the revisions to be pushed diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt index 0557cbbceb..59aec7c3ae 100644 --- a/Documentation/config/user.txt +++ b/Documentation/config/user.txt @@ -13,7 +13,12 @@ committer.email:: Also, all of these can be overridden by the `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, `GIT_COMMITTER_EMAIL` and `EMAIL` environment variables. - See linkgit:git-commit-tree[1] for more information. ++ +Note that the `name` forms of these variables conventionally refer to +some form of a personal name. See linkgit:git-commit[1] and the +environment variables section of linkgit:git[1] for more information on +these settings and the `credential.username` option if you're looking +for authentication credentials instead. user.useConfigOnly:: Instruct Git to avoid trying to guess defaults for `user.email` diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 09faee3b44..bb31f0c42b 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -567,13 +567,13 @@ To illustrate the difference between `-S<regex> --pickaxe-regex` and file: + ---- -+ return !regexec(regexp, two->ptr, 1, ®match, 0); ++ return frotz(nitfol, two->ptr, 1, 0); ... -- hit = !regexec(regexp, mf2.ptr, 1, ®match, 0); +- hit = frotz(nitfol, mf2.ptr, 1, 0); ---- + -While `git log -G"regexec\(regexp"` will show this commit, `git log --S"regexec\(regexp" --pickaxe-regex` will not (because the number of +While `git log -G"frotz\(nitfol"` will show this commit, `git log +-S"frotz\(nitfol" --pickaxe-regex` will not (because the number of occurrences of that string did not change). + Unless `--text` is supplied patches of binary files without a textconv diff --git a/Documentation/doc-diff b/Documentation/doc-diff index 88a9b20168..1694300e50 100755 --- a/Documentation/doc-diff +++ b/Documentation/doc-diff @@ -127,7 +127,7 @@ generate_render_makefile () { while read src do dst=$2/${src#$1/} - printf 'all:: %s\n' "$dst" + printf 'all: %s\n' "$dst" printf '%s: %s\n' "$dst" "$src" printf '\t@echo >&2 " RENDER $(notdir $@)" && \\\n' printf '\tmkdir -p $(dir $@) && \\\n' diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index a2f78624a2..a115a1ae0e 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -139,7 +139,10 @@ ifndef::git-pull[] specified refspec (can be given more than once) to map the refs to remote-tracking branches, instead of the values of `remote.*.fetch` configuration variables for the remote - repository. See section on "Configured Remote-tracking + repository. Providing an empty `<refspec>` to the + `--refmap` option causes Git to ignore the configured + refspecs and rely entirely on the refspecs supplied as + command-line arguments. See section on "Configured Remote-tracking Branches" for details. -t:: diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index bcd85c1976..28d1fee505 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -26,7 +26,10 @@ OPTIONS file. This parameter exists to specify the location of an alternate that only has the objects directory, not a full `.git` directory. The commit-graph file is expected to be in the `<dir>/info` directory and - the packfiles are expected to be in `<dir>/pack`. + the packfiles are expected to be in `<dir>/pack`. If the directory + could not be made into an absolute path, or does not match any known + object directory, `git commit-graph ...` will exit with non-zero + status. --[no-]progress:: Turn progress on/off explicitly. If neither is specified, progress is diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 4b90b9c12a..ec15ee8d6f 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -69,7 +69,6 @@ OPTIONS Do not GPG-sign commit, to countermand a `--gpg-sign` option given earlier on the command line. - Commit Information ------------------ @@ -79,26 +78,6 @@ A commit encapsulates: - author name, email and date - committer name and email and the commit time. -While parent object ids are provided on the command line, author and -committer information is taken from the following environment variables, -if set: - - GIT_AUTHOR_NAME - GIT_AUTHOR_EMAIL - GIT_AUTHOR_DATE - GIT_COMMITTER_NAME - GIT_COMMITTER_EMAIL - GIT_COMMITTER_DATE - -(nb "<", ">" and "\n"s are stripped) - -In case (some of) these environment variables are not set, the information -is taken from the configuration items user.name and user.email, or, if not -present, the environment variable EMAIL, or, if that is not set, -system user name and the hostname used for outgoing mail (taken -from `/etc/mailname` and falling back to the fully qualified hostname when -that file does not exist). - A commit comment is read from stdin. If a changelog entry is not provided via "<" redirection, 'git commit-tree' will just wait for one to be entered and terminated with ^D. @@ -117,6 +96,7 @@ FILES SEE ALSO -------- linkgit:git-write-tree[1] +linkgit:git-commit[1] GIT --- diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index ced5a9beab..13f653989f 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -367,9 +367,6 @@ changes to tracked files. + For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. -:git-commit: 1 -include::date-formats.txt[] - EXAMPLES -------- When recording your own work, the contents of modified files in @@ -463,6 +460,43 @@ alter the order the changes are committed, because the merge should be recorded as a single commit. In fact, the command refuses to run when given pathnames (but see `-i` option). +COMMIT INFORMATION +------------------ + +Author and committer information is taken from the following environment +variables, if set: + + GIT_AUTHOR_NAME + GIT_AUTHOR_EMAIL + GIT_AUTHOR_DATE + GIT_COMMITTER_NAME + GIT_COMMITTER_EMAIL + GIT_COMMITTER_DATE + +(nb "<", ">" and "\n"s are stripped) + +The author and committer names are by convention some form of a personal name +(that is, the name by which other humans refer to you), although Git does not +enforce or require any particular form. Arbitrary Unicode may be used, subject +to the constraints listed above. This name has no effect on authentication; for +that, see the `credential.username` variable in linkgit:git-config[1]. + +In case (some of) these environment variables are not set, the information +is taken from the configuration items `user.name` and `user.email`, or, if not +present, the environment variable EMAIL, or, if that is not set, +system user name and the hostname used for outgoing mail (taken +from `/etc/mailname` and falling back to the fully qualified hostname when +that file does not exist). + +The `author.name` and `committer.name` and their corresponding email options +override `user.name` and `user.email` if set and are overridden themselves by +the environment variables. + +The typical usage is to set just the `user.name` and `user.email` variables; +the other options are provided for more complex use cases. + +:git-commit: 1 +include::date-formats.txt[] DISCUSSION ---------- diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 899e92a1c9..7573160f21 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,18 +9,18 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] name [value [value_regex]] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] name [value [value_regex]] 'git config' [<file-option>] [--type=<type>] --add name value 'git config' [<file-option>] [--type=<type>] --replace-all name value [value_regex] -'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] --get name [value_regex] -'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] --get-all name [value_regex] -'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get name [value_regex] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get-all name [value_regex] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] 'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL 'git config' [<file-option>] --unset name [value_regex] 'git config' [<file-option>] --unset-all name [value_regex] 'git config' [<file-option>] --rename-section old_name new_name 'git config' [<file-option>] --remove-section name -'git config' [<file-option>] [--show-origin] [-z|--null] [--name-only] -l | --list +'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list 'git config' [<file-option>] --get-color name [default] 'git config' [<file-option>] --get-colorbool name [stdout-is-tty] 'git config' [<file-option>] -e | --edit @@ -222,6 +222,11 @@ Valid `<type>`'s include: the actual origin (config file path, ref, or blob id if applicable). +--show-scope:: + Similar to `--show-origin` in that it augments the output of + all queried config options with the scope of that value + (local, global, system, command). + --get-colorbool name [stdout-is-tty]:: Find the color setting for `name` (e.g. `color.diff`) and output diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index a530fef7e5..40ba4aa3e6 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -467,9 +467,9 @@ impossible for a backward-compatible implementation to ever be fast: * In editing files, git-filter-branch by design checks out each and every commit as it existed in the original repo. If your repo has - 10\^5 files and 10\^5 commits, but each commit only modifies 5 - files, then git-filter-branch will make you do 10\^10 modifications, - despite only having (at most) 5*10^5 unique blobs. + `10^5` files and `10^5` commits, but each commit only modifies five + files, then git-filter-branch will make you do `10^10` modifications, + despite only having (at most) `5*10^5` unique blobs. * If you try and cheat and try to make git-filter-branch only work on files modified in a commit, then two things happen diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index c89fb569e3..ddb6acc025 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -59,8 +59,8 @@ grep.extendedRegexp:: other than 'default'. grep.threads:: - Number of grep worker threads to use. If unset (or set to 0), - 8 threads are used by default (for now). + Number of grep worker threads to use. If unset (or set to 0), Git will + use as many threads as the number of logical cores available. grep.fullName:: If set to true, enable `--full-name` option by default. @@ -96,7 +96,8 @@ OPTIONS Recursively search in each submodule that has been initialized and checked out in the repository. When used in combination with the <tree> option the prefix of all submodule output will be the name of - the parent project's <tree> object. + the parent project's <tree> object. This option has no effect + if `--no-index` is given. -a:: --text:: @@ -347,6 +348,17 @@ EXAMPLES `git grep solution -- :^Documentation`:: Looks for `solution`, excluding files in `Documentation`. +NOTES ON THREADS +---------------- + +The `--threads` option (and the grep.threads configuration) will be ignored when +`--open-files-in-pager` is used, forcing a single-threaded execution. + +When grepping the object store (with `--cached` or giving tree objects), running +with multiple threads might perform slower than single threaded if `--textconv` +is given and there're too many text conversions. So if you experience low +performance in this case, it might be desirable to use `--threads=1`. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 974ade2238..a24d90529b 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -41,6 +41,10 @@ COMMANDS To avoid interfering with other worktrees, it first enables the `extensions.worktreeConfig` setting and makes sure to set the `core.sparseCheckout` setting in the worktree-specific config file. ++ +When `--cone` is provided, the `core.sparseCheckoutCone` setting is +also set, allowing for better performance with a limited set of +patterns (see 'CONE PATTERN SET' below). 'set':: Write a set of patterns to the sparse-checkout file, as given as @@ -50,6 +54,14 @@ To avoid interfering with other worktrees, it first enables the + When the `--stdin` option is provided, the patterns are read from standard in as a newline-delimited list instead of from the arguments. ++ +When `core.sparseCheckoutCone` is enabled, the input list is considered a +list of directories instead of sparse-checkout patterns. The command writes +patterns to the sparse-checkout file to include all files contained in those +directories (recursively) as well as files that are siblings of ancestor +directories. The input format matches the output of `git ls-tree --name-only`. +This includes interpreting pathnames that begin with a double quote (") as +C-style quoted strings. 'disable':: Disable the `core.sparseCheckout` config setting, and restore the @@ -106,7 +118,7 @@ The full pattern set allows for arbitrary pattern matches and complicated inclusion/exclusion rules. These can result in O(N*M) pattern matches when updating the index, where N is the number of patterns and M is the number of paths in the index. To combat this performance issue, a more restricted -pattern set is allowed when `core.spareCheckoutCone` is enabled. +pattern set is allowed when `core.sparseCheckoutCone` is enabled. The accepted patterns in the cone pattern set are: @@ -128,9 +140,12 @@ the following patterns: ---------------- This says "include everything in root, but nothing two levels below root." -If we then add the folder `A/B/C` as a recursive pattern, the folders `A` and -`A/B` are added as parent patterns. The resulting sparse-checkout file is -now + +When in cone mode, the `git sparse-checkout set` subcommand takes a list of +directories instead of a list of sparse-checkout patterns. In this mode, +the command `git sparse-checkout set A/B/C` sets the directory `A/B/C` as +a recursive pattern, the directories `A` and `A/B` are added as parent +patterns. The resulting sparse-checkout file is now ---------------- /* diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 5232407f68..218942acd1 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -229,7 +229,7 @@ As an example, the command below will show the path and currently checked out commit for each submodule: + -------------- -git submodule foreach 'echo $path `git rev-parse HEAD`' +git submodule foreach 'echo $sm_path `git rev-parse HEAD`' -------------- sync [--recursive] [--] [<path>...]:: diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index c7a6271daf..1489cb09a0 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -549,6 +549,22 @@ The untracked cache extension can be enabled by the `core.untrackedCache` configuration variable (see linkgit:git-config[1]). +NOTES +----- + +Users often try to use the assume-unchanged and skip-worktree bits +to tell Git to ignore changes to files that are tracked. This does not +work as expected, since Git may still check working tree files against +the index when performing certain operations. In general, Git does not +provide a way to ignore changes to tracked files, so alternate solutions +are recommended. + +For example, if the file you want to change is some sort of config file, +the repository can include a sample config file that can then be copied +into the ignored name and modified. The repository can even include a +script to treat the sample file as a template, modifying and copying it +automatically. + SEE ALSO -------- linkgit:git-config[1], diff --git a/Documentation/git.txt b/Documentation/git.txt index b1597ac002..b0672bd806 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -110,9 +110,23 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config Do not pipe Git output into a pager. --git-dir=<path>:: - Set the path to the repository. This can also be controlled by - setting the `GIT_DIR` environment variable. It can be an absolute - path or relative path to current working directory. + Set the path to the repository (".git" directory). This can also be + controlled by setting the `GIT_DIR` environment variable. It can be + an absolute path or relative path to current working directory. ++ +Specifying the location of the ".git" directory using this +option (or `GIT_DIR` environment variable) turns off the +repository discovery that tries to find a directory with +".git" subdirectory (which is how the repository and the +top-level of the working tree are discovered), and tells Git +that you are at the top level of the working tree. If you +are not at the top-level directory of the working tree, you +should tell Git where the top-level of the working tree is, +with the `--work-tree=<path>` option (or `GIT_WORK_TREE` +environment variable) ++ +If you just want to run git as if it was started in `<path>` then use +`git -C <path>`. --work-tree=<path>:: Set the path to the working tree. It can be an absolute path @@ -482,13 +496,36 @@ double-quotes and respecting backslash escapes. E.g., the value Git Commits ~~~~~~~~~~~ `GIT_AUTHOR_NAME`:: + The human-readable name used in the author identity when creating commit or + tag objects, or when writing reflogs. Overrides the `user.name` and + `author.name` configuration settings. + `GIT_AUTHOR_EMAIL`:: + The email address used in the author identity when creating commit or + tag objects, or when writing reflogs. Overrides the `user.email` and + `author.email` configuration settings. + `GIT_AUTHOR_DATE`:: + The date used for the author identity when creating commit or tag objects, or + when writing reflogs. See linkgit:git-commit[1] for valid formats. + `GIT_COMMITTER_NAME`:: + The human-readable name used in the committer identity when creating commit or + tag objects, or when writing reflogs. Overrides the `user.name` and + `committer.name` configuration settings. + `GIT_COMMITTER_EMAIL`:: + The email address used in the author identity when creating commit or + tag objects, or when writing reflogs. Overrides the `user.email` and + `committer.email` configuration settings. + `GIT_COMMITTER_DATE`:: -'EMAIL':: - see linkgit:git-commit-tree[1] + The date used for the committer identity when creating commit or tag objects, or + when writing reflogs. See linkgit:git-commit[1] for valid formats. + +`EMAIL`:: + The email address used in the author and committer identities if no other + relevant environment variable or configuration setting has been set. Git Diffs ~~~~~~~~~ diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index f880d21dfb..c0b95256cc 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -751,7 +751,7 @@ to it. ================================================ If you make the decision to start your new branch at some other point in the history than the current `HEAD`, you can do so by -just telling 'git checkout' what the base of the checkout would be. +just telling 'git switch' what the base of the checkout would be. In other words, if you have an earlier tag or branch, you'd just do ------------ diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index ea759fdee5..5b9d14fb1f 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -186,7 +186,94 @@ CUSTOM HELPERS -------------- You can write your own custom helpers to interface with any system in -which you keep credentials. See credential.h for details. +which you keep credentials. + +Credential helpers are programs executed by Git to fetch or save +credentials from and to long-term storage (where "long-term" is simply +longer than a single Git process; e.g., credentials may be stored +in-memory for a few minutes, or indefinitely on disk). + +Each helper is specified by a single string in the configuration +variable `credential.helper` (and others, see linkgit:git-config[1]). +The string is transformed by Git into a command to be executed using +these rules: + + 1. If the helper string begins with "!", it is considered a shell + snippet, and everything after the "!" becomes the command. + + 2. Otherwise, if the helper string begins with an absolute path, the + verbatim helper string becomes the command. + + 3. Otherwise, the string "git credential-" is prepended to the helper + string, and the result becomes the command. + +The resulting command then has an "operation" argument appended to it +(see below for details), and the result is executed by the shell. + +Here are some example specifications: + +---------------------------------------------------- +# run "git credential-foo" +foo + +# same as above, but pass an argument to the helper +foo --bar=baz + +# the arguments are parsed by the shell, so use shell +# quoting if necessary +foo --bar="whitespace arg" + +# you can also use an absolute path, which will not use the git wrapper +/path/to/my/helper --with-arguments + +# or you can specify your own shell snippet +!f() { echo "password=`cat $HOME/.secret`"; }; f +---------------------------------------------------- + +Generally speaking, rule (3) above is the simplest for users to specify. +Authors of credential helpers should make an effort to assist their +users by naming their program "git-credential-$NAME", and putting it in +the `$PATH` or `$GIT_EXEC_PATH` during installation, which will allow a +user to enable it with `git config credential.helper $NAME`. + +When a helper is executed, it will have one "operation" argument +appended to its command line, which is one of: + +`get`:: + + Return a matching credential, if any exists. + +`store`:: + + Store the credential, if applicable to the helper. + +`erase`:: + + Remove a matching credential, if any, from the helper's storage. + +The details of the credential will be provided on the helper's stdin +stream. The exact format is the same as the input/output format of the +`git credential` plumbing command (see the section `INPUT/OUTPUT +FORMAT` in linkgit:git-credential[1] for a detailed specification). + +For a `get` operation, the helper should produce a list of attributes on +stdout in the same format (see linkgit:git-credential[1] for common +attributes). A helper is free to produce a subset, or even no values at +all if it has nothing useful to provide. Any provided attributes will +overwrite those already known about by Git. If a helper outputs a +`quit` attribute with a value of `true` or `1`, no further helpers will +be consulted, nor will the user be prompted (if no credential has been +provided, the operation will then fail). + +For a `store` or `erase` operation, the helper's output is ignored. +If it fails to perform the requested operation, it may complain to +stderr to inform the user. If it does not support the requested +operation (e.g., a read-only store), it should silently ignore the +request. + +If a helper receives any other operation, it should silently ignore the +request. This leaves room for future operations to be added (older +helpers will just ignore the new requests). GIT --- diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 50365f2914..3dccab5375 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -490,9 +490,16 @@ fsmonitor-watchman ~~~~~~~~~~~~~~~~~~ This hook is invoked when the configuration option `core.fsmonitor` is -set to `.git/hooks/fsmonitor-watchman`. It takes two arguments, a version -(currently 1) and the time in elapsed nanoseconds since midnight, -January 1, 1970. +set to `.git/hooks/fsmonitor-watchman` or `.git/hooks/fsmonitor-watchmanv2` +depending on the version of the hook to use. + +Version 1 takes two arguments, a version (1) and the time in elapsed +nanoseconds since midnight, January 1, 1970. + +Version 2 takes two arguments, a version (2) and a token that is used +for identifying changes since the token. For watchman this would be +a clock id. This version must output to stdout the new token followed +by a NUL before the list of files. The hook should output to stdout the list of all files in the working directory that may have changed since the requested time. The logic diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 1a7212ce5a..a4b6f49186 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -226,6 +226,7 @@ endif::git-rev-list[] '%GF':: show the fingerprint of the key used to sign a signed commit '%GP':: show the fingerprint of the primary key whose subkey was used to sign a signed commit +'%GT':: show the trust level for the key used to sign a signed commit '%gD':: reflog selector, e.g., `refs/stash@{1}` or `refs/stash@{2 minutes ago}`; the format follows the rules described for the `-g` option. The portion before the `@` is the refname as diff --git a/Documentation/technical/bundle-format.txt b/Documentation/technical/bundle-format.txt new file mode 100644 index 0000000000..0e828151a5 --- /dev/null +++ b/Documentation/technical/bundle-format.txt @@ -0,0 +1,48 @@ += Git bundle v2 format + +The Git bundle format is a format that represents both refs and Git objects. + +== Format + +We will use ABNF notation to define the Git bundle format. See +protocol-common.txt for the details. + +---- +bundle = signature *prerequisite *reference LF pack +signature = "# v2 git bundle" LF + +prerequisite = "-" obj-id SP comment LF +comment = *CHAR +reference = obj-id SP refname LF + +pack = ... ; packfile +---- + +== Semantics + +A Git bundle consists of three parts. + +* "Prerequisites" lists the objects that are NOT included in the bundle and the + reader of the bundle MUST already have, in order to use the data in the + bundle. The objects stored in the bundle may refer to prerequisite objects and + anything reachable from them (e.g. a tree object in the bundle can reference + a blob that is reachable from a prerequisite) and/or expressed as a delta + against prerequisite objects. + +* "References" record the tips of the history graph, iow, what the reader of the + bundle CAN "git fetch" from it. + +* "Pack" is the pack data stream "git fetch" would send, if you fetch from a + repository that has the references recorded in the "References" above into a + repository that has references pointing at the objects listed in + "Prerequisites" above. + +In the bundle format, there can be a comment following a prerequisite obj-id. +This is a comment and it has no specific meaning. The writer of the bundle MAY +put any string here. The reader of the bundle MUST ignore the comment. + +=== Note on the shallow clone and a Git bundle + +Note that the prerequisites does not represent a shallow-clone boundary. The +semantics of the prerequisites and the shallow-clone boundaries are different, +and the Git bundle v2 format cannot represent a shallow clone repository. diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index cab5bdd2ff..d3a142c652 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -315,10 +315,11 @@ CHUNK DATA: Stores two 4-byte values for every object. 1: The pack-int-id for the pack storing this object. 2: The offset within the pack. - If all offsets are less than 2^31, then the large offset chunk + If all offsets are less than 2^32, then the large offset chunk will not exist and offsets are stored as in IDX v1. If there is at least one offset value larger than 2^32-1, then - the large offset chunk must exist. If the large offset chunk + the large offset chunk must exist, and offsets larger than + 2^31-1 must be stored in it instead. If the large offset chunk exists and the 31st bit is on, then removing that bit reveals the row in the large offsets containing the 8-byte offset of this object. |