diff options
Diffstat (limited to 'Documentation')
38 files changed, 881 insertions, 230 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index b980407059..81d1bf7a04 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -21,6 +21,7 @@ MAN1_TXT += gitweb.txt MAN5_TXT += gitattributes.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt +MAN5_TXT += gitmailmap.txt MAN5_TXT += gitmodules.txt MAN5_TXT += gitrepository-layout.txt MAN5_TXT += gitweb.conf.txt diff --git a/Documentation/RelNotes/2.30.1.txt b/Documentation/RelNotes/2.30.1.txt new file mode 100644 index 0000000000..249ef1492f --- /dev/null +++ b/Documentation/RelNotes/2.30.1.txt @@ -0,0 +1,55 @@ +Git v2.30.1 Release Notes +========================= + +This release is primarily to merge fixes accumulated on the 'master' +front to prepare for 2.31 release that are still relevant to 2.30.x +maintenance track. + +Fixes since v2.30 +----------------- + + * "git fetch --recurse-submodules" failed to update a submodule + when it has an uninitialized (hence of no interest to the user) + sub-submodule, which has been corrected. + + * Command line error of "git rebase" are diagnosed earlier. + + * "git stash" did not work well in a sparsely checked out working + tree. + + * Some tests expect that "ls -l" output has either '-' or 'x' for + group executable bit, but setgid bit can be inherited from parent + directory and make these fields 'S' or 's' instead, causing test + failures. + + * "git for-each-repo --config=<var> <cmd>" should not run <cmd> for + any repository when the configuration variable <var> is not defined + even once. + + * "git mergetool --tool-help" was broken in 2.29 and failed to list + all the available tools. + + * Fix for procedure to building CI test environment for mac. + + * Newline characters in the host and path part of git:// URL are + now forbidden. + + * When more than one commit with the same patch ID appears on one + side, "git log --cherry-pick A...B" did not exclude them all when a + commit with the same patch ID appears on the other side. Now it + does. + + * Documentation for "git fsck" lost stale bits that has become + incorrect. + + * Doc for packfile URI feature has been clarified. + + * The implementation of "git branch --sort" wrt the detached HEAD + display has always been hacky, which has been cleaned up. + + * Our setting of GitHub CI test jobs were a bit too eager to give up + once there is even one failure found. Tweak the knob to allow + other jobs keep running even when we see a failure, so that we can + find more failures in a single run. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.31.0.txt b/Documentation/RelNotes/2.31.0.txt new file mode 100644 index 0000000000..905c9aa52b --- /dev/null +++ b/Documentation/RelNotes/2.31.0.txt @@ -0,0 +1,201 @@ +Git 2.31 Release Notes +====================== + +Updates since v2.30 +------------------- + +Backward incompatible and other important changes + + * The "pack-redundant" command, which has been left stale with almost + unusable performance issues, now warns loudly when it gets used, as + we no longer want to recommend its use (instead just "repack -d" + instead). + + * The development community has adopted Contributor Covenant v2.0 to + update from v1.4 that we have been using. + + +UI, Workflows & Features + + * The "--format=%(trailers)" mechanism gets enhanced to make it + easier to design output for machine consumption. + + * When a user does not tell "git pull" to use rebase or merge, the + command gives a loud message telling a user to choose between + rebase or merge but creates a merge anyway, forcing users who would + want to rebase to redo the operation. Fix an early part of this + problem by tightening the condition to give the message---there is + no reason to stop or force the user to choose between rebase or + merge if the history fast-forwards. + + * The configuration variable 'core.abbrev' can be set to 'no' to + force no abbreviation regardless of the hash algorithm. + + * "git rev-parse" can be explicitly told to give output as absolute + or relative path with the `--path-format=(absolute|relative)` option. + + * Bash completion (in contrib/) update to make it easier for + end-users to add completion for their custom "git" subcommands. + + * "git maintenance" learned to drive scheduled maintenance on + platforms whose native scheduling methods are not 'cron'. + + * After expiring a reflog and making a single commit, the reflog for + the branch would record a single entry that knows both @{0} and + @{1}, but we failed to answer "what commit were we on?", i.e. @{1} + + * "git bundle" learns "--stdin" option to read its refs from the + standard input. Also, it now does not lose refs whey they point + at the same object. + + * "git log" learned a new "--diff-merges=<how>" option. + + * "git ls-files" can and does show multiple entries when the index is + unmerged, which is a source for confusion unless -s/-u option is in + use. A new option --deduplicate has been introduced. + + +Performance, Internal Implementation, Development Support etc. + + * A 3-year old test that was not testing anything useful has been + corrected. + + * Retire more names with "sha1" in it. + + * The topological walk codepath is covered by new trace2 stats. + + * Update the Code-of-conduct to version 2.0 from the upstream (we've + been using version 1.4). + + * "git mktag" validates its input using its own rules before writing + a tag object---it has been updated to share the logic with "git + fsck". + + * Two new ways to feed configuration variable-value pairs via + environment variables have been introduced, and the way + GIT_CONFIG_PARAMETERS encodes variable/value pairs has been tweaked + to make it more robust. + + * Tests have been updated so that they do not to get affected by the + name of the default branch "git init" creates. + + * "git fetch" learns to treat ref updates atomically in all-or-none + fashion, just like "git push" does, with the new "--atomic" option. + + * The peel_ref() API has been replaced with peel_iterated_oid(). + + * The .use_shell flag in struct child_process that is passed to + run_command() API has been clarified with a bit more documentation. + + * Document, clean-up and optimize the code around the cache-tree + extension in the index. + + * The ls-refs protocol operation has been optimized to narrow the + sub-hierarchy of refs/ it walks to produce response. + + * When removing many branches and tags, the code used to do so one + ref at a time. There is another API it can use to delete multiple + refs, and it makes quite a lot of performance difference when the + refs are packed. + + * The "pack-objects" command needs to iterate over all the tags when + automatic tag following is enabled, but it actually iterated over + all refs and then discarded everything outside "refs/tags/" + hierarchy, which was quite wasteful. + + * A perf script was made more portable. + (merge f08b6c553d jk/p5303-sed-portability-fix later to maint). + + * Our setting of GitHub CI test jobs were a bit too eager to give up + once there is even one failure found. Tweak the knob to allow + other jobs keep running even when we see a failure, so that we can + find more failures in a single run. + (merge 2b0e14f640 pb/ci-matrix-wo-shortcut later to maint). + + * We've carried compatibility codepaths for compilers without + variadic macros for quite some time, but the world may be ready for + them to be removed. Force compilation failure on exotic platforms + where variadic macros are not available to find out who screams in + such a way that we can easily revert if it turns out that the world + is not yet ready. + + +Fixes since v2.30 +----------------- + + * Diagnose command line error of "git rebase" early. + (merge ca5120c339 rs/rebase-commit-validation later to maint). + + * Clean up option descriptions in "git cmd --help". + (merge e73fe3dd02 zh/arg-help-format later to maint). + + * "git stash" did not work well in a sparsely checked out working + tree. + (merge ba359fd507 en/stash-apply-sparse-checkout later to maint). + + * Some tests expect that "ls -l" output has either '-' or 'x' for + group executable bit, but setgid bit can be inherited from parent + directory and make these fields 'S' or 's' instead, causing test + failures. + (merge ea8bbf2a4e mt/t4129-with-setgid-dir later to maint). + + * "git for-each-repo --config=<var> <cmd>" should not run <cmd> for + any repository when the configuration variable <var> is not defined + even once. + (merge 6c62f01552 ds/for-each-repo-noopfix later to maint). + + * Fix 2.29 regression where "git mergetool --tool-help" fails to list + all the available tools. + (merge 80f5a16798 pb/mergetool-tool-help-fix later to maint). + + * Fix for procedure to building CI test environment for mac. + (merge 3831132ace jc/macos-install-dependencies-fix later to maint). + + * The implementation of "git branch --sort" wrt the detached HEAD + display has always been hacky, which has been cleaned up. + (merge 4045f659bd ab/branch-sort later to maint). + + * Newline characters in the host and path part of git:// URL are + now forbidden. + (merge 6aed56736b jk/forbid-lf-in-git-url later to maint). + + * "git diff" showed a submodule working tree with untracked cruft as + "Submodule commit <objectname>-dirty", but a natural expectation is + that the "-dirty" indicator would align with "git describe --dirty", + which does not consider having untracked files in the working tree + as source of dirtiness. The inconsistency has been fixed. + + * When more than one commit with the same patch ID appears on one + side, "git log --cherry-pick A...B" did not exclude them all when a + commit with the same patch ID appears on the other side. Now it + does. + (merge c9e3a4e76d jk/log-cherry-pick-duplicate-patches later to maint). + + * Documentation for "git fsck" lost stale bits that has become + incorrect. + (merge 28cc00a13d ab/fsck-doc-fix later to maint). + + * Doc fix for packfile URI feature. + (merge bfc2a36ff2 jt/packfile-as-uri-doc later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 505a276596 pk/subsub-fetch-fix-take-2 later to maint). + (merge 33fc56253b fc/t6030-bisect-reset-removes-auxiliary-files later to maint). + (merge 7efc378205 ta/doc-typofix later to maint). + (merge 1f4e9319c7 pb/doc-modules-git-work-tree-typofix later to maint). + (merge 04f6b0a192 ma/t1300-cleanup later to maint). + (merge 7b77f5a13e ma/doc-pack-format-varint-for-sizes later to maint). + (merge cc2d43be2b nk/perf-fsmonitor-cleanup later to maint). + (merge c8302c6c00 ar/t6016-modernise later to maint). + (merge 0454986e78 jc/sign-off later to maint). + (merge 155067ab4f vv/send-email-with-less-secure-apps-access later to maint). + (merge acaabcf391 jk/t5516-deflake later to maint). + (merge a1e03535db ad/t4129-setfacl-target-fix later to maint). + (merge b356d23638 ug/doc-lose-dircache later to maint). + (merge 9371c0e9dd ab/gettext-charset-comment-fix later to maint). + (merge 52fc4f195c dl/p4-encode-after-kw-expansion later to maint). + (merge 4eb56b56e7 bc/doc-status-short later to maint). + (merge a4a1ca22ef tb/local-clone-race-doc later to maint). + (merge 6a8c89d053 ma/more-opaque-lock-file later to maint). + (merge 4a5ec7d166 js/skip-dashed-built-ins-from-config-mak later to maint). + (merge 6eaf624dea pb/blame-funcname-range-userdiff later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index d12094bac5..0452db2e67 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -307,7 +307,7 @@ wrote the patch or have the right to pass it on under the same license as ours, by "signing off" your patch. Without sign-off, we cannot accept your patches. -If you can certify the below D-C-O: +If (and only if) you certify the below D-C-O: [[dco]] .Developer's Certificate of Origin 1.1 diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index 160aacad84..c04f62a54a 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -625,4 +625,6 @@ core.abbrev:: computed based on the approximate number of packed objects in your repository, which hopefully is enough for abbreviated object names to stay unique for some time. + If set to "no", no abbreviation is made and the object names + are shown in their full length. The minimum length is 4. diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index c3ae136eba..2d3331f55c 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -85,6 +85,8 @@ diff.ignoreSubmodules:: and 'git status' when `status.submoduleSummary` is set unless it is overridden by using the --ignore-submodules command-line option. The 'git submodule' commands are not affected by this setting. + By default this is set to untracked so that any untracked + submodules are ignored. diff.mnemonicPrefix:: If set, 'git diff' uses a prefix pair that is different from the diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt index 3968fbb697..7003661c0d 100644 --- a/Documentation/config/http.txt +++ b/Documentation/config/http.txt @@ -42,12 +42,12 @@ http.proxySSLKey:: http.proxySSLCertPasswordProtected:: Enable Git's password prompt for the proxy SSL certificate. Otherwise OpenSSL will prompt the user, possibly many times, if the certificate or private key - is encrypted. Can be overriden by the `GIT_PROXY_SSL_CERT_PASSWORD_PROTECTED` + is encrypted. Can be overridden by the `GIT_PROXY_SSL_CERT_PASSWORD_PROTECTED` environment variable. http.proxySSLCAInfo:: Pathname to the file containing the certificate bundle that should be used to - verify the proxy with when using an HTTPS proxy. Can be overriden by the + verify the proxy with when using an HTTPS proxy. Can be overridden by the `GIT_PROXY_SSL_CAINFO` environment variable. http.emptyAuth:: diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.txt index 01d3afd8a8..fe1642f0d4 100644 --- a/Documentation/config/trace2.txt +++ b/Documentation/config/trace2.txt @@ -54,7 +54,7 @@ trace2.envVars:: `GIT_HTTP_USER_AGENT,GIT_CONFIG` would cause the trace2 output to contain events listing the overrides for HTTP user agent and the location of the Git configuration file (assuming any are set). May be - overriden by the `GIT_TRACE2_ENV_VARS` environment variable. Unset by + overridden by the `GIT_TRACE2_ENV_VARS` environment variable. Unset by default. trace2.destinationDebug:: diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index b10ff4caa6..2db8eacc3e 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -81,9 +81,9 @@ Combined diff format Any diff-generating command can take the `-c` or `--cc` option to produce a 'combined diff' when showing a merge. This is the default format when showing merges with linkgit:git-diff[1] or -linkgit:git-show[1]. Note also that you can give the `-m` option to any -of these commands to force generation of diffs with individual parents -of a merge. +linkgit:git-show[1]. Note also that you can give suitable +`--diff-merges` option to any of these commands to force generation of +diffs in specific format. A "combined diff" format looks like this: diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 746b144c76..e5733ccb2d 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -33,6 +33,57 @@ endif::git-diff[] show the patch by default, or to cancel the effect of `--patch`. endif::git-format-patch[] +ifdef::git-log[] +--diff-merges=(off|none|first-parent|1|separate|m|combined|c|dense-combined|cc):: +--no-diff-merges:: + Specify diff format to be used for merge commits. Default is + {diff-merges-default} unless `--first-parent` is in use, in which case + `first-parent` is the default. ++ +--diff-merges=(off|none)::: +--no-diff-merges::: + Disable output of diffs for merge commits. Useful to override + implied value. ++ +--diff-merges=first-parent::: +--diff-merges=1::: + This option makes merge commits show the full diff with + respect to the first parent only. ++ +--diff-merges=separate::: +--diff-merges=m::: +-m::: + This makes merge commits show the full diff with respect to + each of the parents. Separate log entry and diff is generated + for each parent. `-m` doesn't produce any output without `-p`. ++ +--diff-merges=combined::: +--diff-merges=c::: +-c::: + With this option, diff output for a merge commit shows the + differences from each of the parents to the merge result + simultaneously instead of showing pairwise diff between a + parent and the result one at a time. Furthermore, it lists + only files which were modified from all parents. `-c` implies + `-p`. ++ +--diff-merges=dense-combined::: +--diff-merges=cc::: +--cc::: + With this option the output produced by + `--diff-merges=combined` is further compressed by omitting + uninteresting hunks whose contents in the parents have only + two variants and the merge result picks one of them without + modification. `--cc` implies `-p`. + +--combined-all-paths:: + This flag causes combined diffs (used for merge commits) to + list the name of the file from all parents. It thus only has + effect when `--diff-merges=[dense-]combined` is in use, and + is likely only useful if filename changes are detected (i.e. + when either rename or copy detection have been requested). +endif::git-log[] + -U<n>:: --unified=<n>:: Generate diffs with <n> lines of context instead of diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 2bf77b46fd..07783deee3 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -7,6 +7,10 @@ existing contents of `.git/FETCH_HEAD`. Without this option old data in `.git/FETCH_HEAD` will be overwritten. +--atomic:: + Use an atomic transaction to update local refs. Either all refs are + updated, or on error, no refs are updated. + --depth=<depth>:: Limit fetching to the specified number of commits from the tip of each remote branch history. If fetching to a 'shallow' repository diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 34b496d485..3bf5d5d8b4 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -226,7 +226,7 @@ commit commentary), a blame viewer will not care. MAPPING AUTHORS --------------- -include::mailmap.txt[] +See linkgit:gitmailmap[5]. SEE ALSO diff --git a/Documentation/git-check-mailmap.txt b/Documentation/git-check-mailmap.txt index aa2055dbeb..02f4418323 100644 --- a/Documentation/git-check-mailmap.txt +++ b/Documentation/git-check-mailmap.txt @@ -36,10 +36,17 @@ name is provided or known to the 'mailmap', ``Name $$<user@host>$$'' is printed; otherwise only ``$$<user@host>$$'' is printed. +CONFIGURATION +------------- + +See `mailmap.file` and `mailmap.blob` in linkgit:git-config[1] for how +to specify a custom `.mailmap` target file or object. + + MAPPING AUTHORS --------------- -include::mailmap.txt[] +See linkgit:gitmailmap[5]. GIT diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 876aedcd47..02d9c19cec 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -57,6 +57,10 @@ repository is specified as a URL, then this flag is ignored (and we never use the local optimizations). Specifying `--no-local` will override the default when `/path/to/repo` is given, using the regular Git transport instead. ++ +*NOTE*: this operation can race with concurrent modification to the +source repository, similar to running `cp -r src dst` while modifying +`src`. --no-hardlinks:: Force the cloning process from a repository on a local diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 0e9351d3cb..4b4cc5c5e8 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -346,6 +346,22 @@ GIT_CONFIG_NOSYSTEM:: See also <<FILES>>. +GIT_CONFIG_COUNT:: +GIT_CONFIG_KEY_<n>:: +GIT_CONFIG_VALUE_<n>:: + If GIT_CONFIG_COUNT is set to a positive number, all environment pairs + GIT_CONFIG_KEY_<n> and GIT_CONFIG_VALUE_<n> up to that number will be + added to the process's runtime configuration. The config pairs are + zero-indexed. Any missing key or value is treated as an error. An empty + GIT_CONFIG_COUNT is treated the same as GIT_CONFIG_COUNT=0, namely no + pairs are processed. These environment variables will override values + in configuration files, but will be overridden by any explicit options + passed via `git -c`. ++ +This is useful for cases where you want to spawn multiple git commands +with a common configuration but cannot depend on a configuration file, +for example when writing scripts. + [[EXAMPLES]] EXAMPLES diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index d72d15be5b..bd596619c0 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -129,14 +129,6 @@ using 'git commit-graph verify'. See linkgit:git-commit-graph[1]. Extracted Diagnostics --------------------- -expect dangling commits - potential heads - due to lack of head information:: - You haven't specified any nodes as heads so it won't be - possible to differentiate between un-parented commits and - root nodes. - -missing sha1 directory '<dir>':: - The directory holding the sha1 objects is missing. - unreachable <type> <object>:: The <type> object <object>, isn't actually referred to directly or indirectly in any of the trees or commits seen. This can diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index dd189a353a..1bbf865a1b 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -107,47 +107,15 @@ DIFF FORMATTING By default, `git log` does not generate any diff output. The options below can be used to show the changes made by each commit. -Note that unless one of `-c`, `--cc`, or `-m` is given, merge commits -will never show a diff, even if a diff format like `--patch` is -selected, nor will they match search options like `-S`. The exception is -when `--first-parent` is in use, in which merges are treated like normal -single-parent commits (this can be overridden by providing a -combined-diff option or with `--no-diff-merges`). - --c:: - With this option, diff output for a merge commit - shows the differences from each of the parents to the merge result - simultaneously instead of showing pairwise diff between a parent - and the result one at a time. Furthermore, it lists only files - which were modified from all parents. - ---cc:: - This flag implies the `-c` option and further compresses the - patch output by omitting uninteresting hunks whose contents in - the parents have only two variants and the merge result picks - one of them without modification. - ---combined-all-paths:: - This flag causes combined diffs (used for merge commits) to - list the name of the file from all parents. It thus only has - effect when -c or --cc are specified, and is likely only - useful if filename changes are detected (i.e. when either - rename or copy detection have been requested). - --m:: - This flag makes the merge commits show the full diff like - regular commits; for each merge parent, a separate log entry - and diff is generated. An exception is that only diff against - the first parent is shown when `--first-parent` option is given; - in that case, the output represents the changes the merge - brought _into_ the then-current branch. - ---diff-merges=off:: ---no-diff-merges:: - Disable output of diffs for merge commits (default). Useful to - override `-m`, `-c`, or `--cc`. +Note that unless one of `--diff-merges` variants (including short +`-m`, `-c`, and `--cc` options) is explicitly given, merge commits +will not show a diff, even if a diff format like `--patch` is +selected, nor will they match search options like `-S`. The exception +is when `--first-parent` is in use, in which case `first-parent` is +the default format. :git-log: 1 +:diff-merges-default: `off` include::diff-options.txt[] include::diff-generate-patch.txt[] diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index cbcf5263dd..6d11ab506b 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -13,6 +13,7 @@ SYNOPSIS (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* (-[c|d|o|i|s|u|k|m])* [--eol] + [--deduplicate] [-x <pattern>|--exclude=<pattern>] [-X <file>|--exclude-from=<file>] [--exclude-per-directory=<file>] @@ -23,9 +24,8 @@ SYNOPSIS DESCRIPTION ----------- -This merges the file listing in the directory cache index with the -actual working directory list, and shows different combinations of the -two. +This merges the file listing in the index with the actual working +directory list, and shows different combinations of the two. One or more of the options below may be used to determine the files shown: @@ -81,6 +81,13 @@ OPTIONS \0 line termination on output and do not quote filenames. See OUTPUT below for more information. +--deduplicate:: + When only filenames are shown, suppress duplicates that may + come from having multiple stages during a merge, or giving + `--deleted` and `--modified` option at the same time. + When any of the `-t`, `--unmerged`, or `--stage` option is + in use, this option has no effect. + -x <pattern>:: --exclude=<pattern>:: Skip untracked files matching pattern. diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt index d1f9b5172d..3b432171d6 100644 --- a/Documentation/git-maintenance.txt +++ b/Documentation/git-maintenance.txt @@ -38,7 +38,7 @@ register:: for running in the background without disrupting foreground processes. + -The `register` subcomand will also set the `maintenance.strategy` config +The `register` subcommand will also set the `maintenance.strategy` config value to `incremental`, if this value is not previously set. The `incremental` strategy uses the following schedule for each maintenance task: @@ -218,6 +218,122 @@ Further, the `git gc` command should not be combined with but does not take the lock in the same way as `git maintenance run`. If possible, use `git maintenance run --task=gc` instead of `git gc`. +The following sections describe the mechanisms put in place to run +background maintenance by `git maintenance start` and how to customize +them. + +BACKGROUND MAINTENANCE ON POSIX SYSTEMS +--------------------------------------- + +The standard mechanism for scheduling background tasks on POSIX systems +is cron(8). This tool executes commands based on a given schedule. The +current list of user-scheduled tasks can be found by running `crontab -l`. +The schedule written by `git maintenance start` is similar to this: + +----------------------------------------------------------------------- +# BEGIN GIT MAINTENANCE SCHEDULE +# The following schedule was created by Git +# Any edits made in this region might be +# replaced in the future by a Git command. + +0 1-23 * * * "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=hourly +0 0 * * 1-6 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=daily +0 0 * * 0 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=weekly + +# END GIT MAINTENANCE SCHEDULE +----------------------------------------------------------------------- + +The comments are used as a region to mark the schedule as written by Git. +Any modifications within this region will be completely deleted by +`git maintenance stop` or overwritten by `git maintenance start`. + +The `crontab` entry specifies the full path of the `git` executable to +ensure that the executed `git` command is the same one with which +`git maintenance start` was issued independent of `PATH`. If the same user +runs `git maintenance start` with multiple Git executables, then only the +latest executable is used. + +These commands use `git for-each-repo --config=maintenance.repo` to run +`git maintenance run --schedule=<frequency>` on each repository listed in +the multi-valued `maintenance.repo` config option. These are typically +loaded from the user-specific global config. The `git maintenance` process +then determines which maintenance tasks are configured to run on each +repository with each `<frequency>` using the `maintenance.<task>.schedule` +config options. These values are loaded from the global or repository +config values. + +If the config values are insufficient to achieve your desired background +maintenance schedule, then you can create your own schedule. If you run +`crontab -e`, then an editor will load with your user-specific `cron` +schedule. In that editor, you can add your own schedule lines. You could +start by adapting the default schedule listed earlier, or you could read +the crontab(5) documentation for advanced scheduling techniques. Please +do use the full path and `--exec-path` techniques from the default +schedule to ensure you are executing the correct binaries in your +schedule. + + +BACKGROUND MAINTENANCE ON MACOS SYSTEMS +--------------------------------------- + +While macOS technically supports `cron`, using `crontab -e` requires +elevated privileges and the executed process does not have a full user +context. Without a full user context, Git and its credential helpers +cannot access stored credentials, so some maintenance tasks are not +functional. + +Instead, `git maintenance start` interacts with the `launchctl` tool, +which is the recommended way to schedule timed jobs in macOS. Scheduling +maintenance through `git maintenance (start|stop)` requires some +`launchctl` features available only in macOS 10.11 or later. + +Your user-specific scheduled tasks are stored as XML-formatted `.plist` +files in `~/Library/LaunchAgents/`. You can see the currently-registered +tasks using the following command: + +----------------------------------------------------------------------- +$ ls ~/Library/LaunchAgents/org.git-scm.git* +org.git-scm.git.daily.plist +org.git-scm.git.hourly.plist +org.git-scm.git.weekly.plist +----------------------------------------------------------------------- + +One task is registered for each `--schedule=<frequency>` option. To +inspect how the XML format describes each schedule, open one of these +`.plist` files in an editor and inspect the `<array>` element following +the `<key>StartCalendarInterval</key>` element. + +`git maintenance start` will overwrite these files and register the +tasks again with `launchctl`, so any customizations should be done by +creating your own `.plist` files with distinct names. Similarly, the +`git maintenance stop` command will unregister the tasks with `launchctl` +and delete the `.plist` files. + +To create more advanced customizations to your background tasks, see +launchctl.plist(5) for more information. + + +BACKGROUND MAINTENANCE ON WINDOWS SYSTEMS +----------------------------------------- + +Windows does not support `cron` and instead has its own system for +scheduling background tasks. The `git maintenance start` command uses +the `schtasks` command to submit tasks to this system. You can inspect +all background tasks using the Task Scheduler application. The tasks +added by Git have names of the form `Git Maintenance (<frequency>)`. +The Task Scheduler GUI has ways to inspect these tasks, but you can also +export the tasks to XML files and view the details there. + +Note that since Git is a console application, these background tasks +create a console window visible to the current user. This can be changed +manually by selecting the "Run whether user is logged in or not" option +in Task Scheduler. This change requires a password input, which is why +`git maintenance start` does not select it by default. + +If you want to customize the background tasks, please rename the tasks +so future calls to `git maintenance (start|stop)` do not overwrite your +custom tasks. + GIT --- diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt index fa6a756123..17a2603a60 100644 --- a/Documentation/git-mktag.txt +++ b/Documentation/git-mktag.txt @@ -3,7 +3,7 @@ git-mktag(1) NAME ---- -git-mktag - Creates a tag object +git-mktag - Creates a tag object with extra validation SYNOPSIS @@ -11,25 +11,52 @@ SYNOPSIS [verse] 'git mktag' +OPTIONS +------- + +--strict:: + By default mktag turns on the equivalent of + linkgit:git-fsck[1] `--strict` mode. Use `--no-strict` to + disable it. + DESCRIPTION ----------- -Reads a tag contents on standard input and creates a tag object -that can also be used to sign other objects. -The output is the new tag's <object> identifier. +Reads a tag contents on standard input and creates a tag object. The +output is the new tag's <object> identifier. + +This command is mostly equivalent to linkgit:git-hash-object[1] +invoked with `-t tag -w --stdin`. I.e. both of these will create and +write a tag found in `my-tag`: + + git mktag <my-tag + git hash-object -t tag -w --stdin <my-tag + +The difference is that mktag will die before writing the tag if the +tag doesn't pass a linkgit:git-fsck[1] check. + +The "fsck" check done mktag is stricter than what linkgit:git-fsck[1] +would run by default in that all `fsck.<msg-id>` messages are promoted +from warnings to errors (so e.g. a missing "tagger" line is an error). + +Extra headers in the object are also an error under mktag, but ignored +by linkgit:git-fsck[1]. This extra check can be turned off by setting +the appropriate `fsck.<msg-id>` varible: + + git -c fsck.extraHeaderEntry=ignore mktag <my-tag-with-headers Tag Format ---------- A tag signature file, to be fed to this command's standard input, has a very simple fixed format: four lines of - object <sha1> + object <hash> type <typename> tag <tagname> tagger <tagger> followed by some 'optional' free-form message (some tags created -by older Git may not have `tagger` line). The message, when +by older Git may not have `tagger` line). The message, when it exists, is separated by a blank line from the header. The message part may contain a signature that Git itself doesn't care about, but that can be verified with gpg. diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index ec233ac0c1..f89e68b424 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -397,7 +397,7 @@ changelist text. Exiting with a non-zero status from the script will abort the process. The purpose of the hook is to edit the message file in place, -and it is not supressed by the `--no-verify` option. This hook +and it is not suppressed by the `--no-verify` option. This hook is called even if `--prepare-p4-only` is set. p4-changelist diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 5013daa6ef..6b8ca085aa 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -212,6 +212,18 @@ Options for Files Only the names of the variables are listed, not their value, even if they are set. +--path-format=(absolute|relative):: + Controls the behavior of certain other options. If specified as absolute, the + paths printed by those options will be absolute and canonical. If specified as + relative, the paths will be relative to the current working directory if that + is possible. The default is option specific. ++ +This option may be specified multiple times and affects only the arguments that +follow it on the command line, either to the end of the command line or the next +instance of this option. + +The following options are modified by `--path-format`: + --git-dir:: Show `$GIT_DIR` if defined. Otherwise show the path to the .git directory. The path shown, when relative, is @@ -221,27 +233,9 @@ If `$GIT_DIR` is not defined and the current directory is not detected to lie in a Git repository or work tree print a message to stderr and exit with nonzero status. ---absolute-git-dir:: - Like `--git-dir`, but its output is always the canonicalized - absolute path. - --git-common-dir:: Show `$GIT_COMMON_DIR` if defined, else `$GIT_DIR`. ---is-inside-git-dir:: - When the current working directory is below the repository - directory print "true", otherwise "false". - ---is-inside-work-tree:: - When the current working directory is inside the work tree of the - repository print "true", otherwise "false". - ---is-bare-repository:: - When the repository is bare print "true", otherwise "false". - ---is-shallow-repository:: - When the repository is shallow print "true", otherwise "false". - --resolve-git-dir <path>:: Check if <path> is a valid repository or a gitfile that points at a valid repository, and print the location of the @@ -255,19 +249,9 @@ print a message to stderr and exit with nonzero status. $GIT_OBJECT_DIRECTORY is set to /foo/bar then "git rev-parse --git-path objects/abc" returns /foo/bar/abc. ---show-cdup:: - When the command is invoked from a subdirectory, show the - path of the top-level directory relative to the current - directory (typically a sequence of "../", or an empty string). - ---show-prefix:: - When the command is invoked from a subdirectory, show the - path of the current directory relative to the top-level - directory. - --show-toplevel:: - Show the absolute path of the top-level directory of the working - tree. If there is no working tree, report an error. + Show the (by default, absolute) path of the top-level directory + of the working tree. If there is no working tree, report an error. --show-superproject-working-tree:: Show the absolute path of the root of the superproject's @@ -279,6 +263,36 @@ print a message to stderr and exit with nonzero status. Show the path to the shared index file in split index mode, or empty if not in split-index mode. +The following options are unaffected by `--path-format`: + +--absolute-git-dir:: + Like `--git-dir`, but its output is always the canonicalized + absolute path. + +--is-inside-git-dir:: + When the current working directory is below the repository + directory print "true", otherwise "false". + +--is-inside-work-tree:: + When the current working directory is inside the work tree of the + repository print "true", otherwise "false". + +--is-bare-repository:: + When the repository is bare print "true", otherwise "false". + +--is-shallow-repository:: + When the repository is shallow print "true", otherwise "false". + +--show-cdup:: + When the command is invoked from a subdirectory, show the + path of the top-level directory relative to the current + directory (typically a sequence of "../", or an empty string). + +--show-prefix:: + When the command is invoked from a subdirectory, show the + path of the current directory relative to the top-level + directory. + --show-object-format[=(storage|input|output)]:: Show the object format (hash algorithm) used for the repository for storage inside the `.git` directory, input, or output. For diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index b7bbbeadef..93708aefea 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -494,10 +494,14 @@ edit ~/.gitconfig to specify your account settings: smtpServerPort = 587 ---- -If you have multifactor authentication setup on your gmail account, you will +If you have multi-factor authentication set up on your Gmail account, you will need to generate an app-specific password for use with 'git send-email'. Visit https://security.google.com/settings/security/apppasswords to create it. +If you do not have multi-factor authentication set up on your Gmail account, +you will need to allow less secure app access. Visit +https://myaccount.google.com/lesssecureapps to enable it. + Once your commits are ready to be sent to the mailing list, run the following commands: diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index fd93cd41e9..c16cc3b608 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -111,11 +111,7 @@ include::rev-list-options.txt[] MAPPING AUTHORS --------------- -The `.mailmap` feature is used to coalesce together commits by the same -person in the shortlog, where their name and/or email address was -spelled differently. - -include::mailmap.txt[] +See linkgit:gitmailmap[5]. GIT --- diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index fcf528c1b3..2b1bc7288d 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -45,10 +45,13 @@ include::pretty-options.txt[] include::pretty-formats.txt[] -COMMON DIFF OPTIONS -------------------- +DIFF FORMATTING +--------------- +The options below can be used to change the way `git show` generates +diff output. :git-log: 1 +:diff-merges-default: `dense-combined` include::diff-options.txt[] include::diff-generate-patch.txt[] diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 7731b45f07..c0764e850a 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -184,11 +184,26 @@ characters, that field will be quoted in the manner of a C string literal: surrounded by ASCII double quote (34) characters, and with interior special characters backslash-escaped. -For paths with merge conflicts, `X` and `Y` show the modification -states of each side of the merge. For paths that do not have merge -conflicts, `X` shows the status of the index, and `Y` shows the status -of the work tree. For untracked paths, `XY` are `??`. Other status -codes can be interpreted as follows: +There are three different types of states that are shown using this format, and +each one uses the `XY` syntax differently: + +* When a merge is occurring and the merge was successful, or outside of a merge + situation, `X` shows the status of the index and `Y` shows the status of the + working tree. +* When a merge conflict has occurred and has not yet been resolved, `X` and `Y` + show the state introduced by each head of the merge, relative to the common + ancestor. These paths are said to be _unmerged_. +* When a path is untracked, `X` and `Y` are always the same, since they are + unknown to the index. `??` is used for untracked paths. Ignored files are + not listed unless `--ignored` is used; if it is, ignored files are indicated + by `!!`. + +Note that the term _merge_ here also includes rebases using the default +`--merge` strategy, cherry-picks, and anything else using the merge machinery. + +In the following table, these three classes are shown in separate sections, and +these characters are used for `X` and `Y` fields for the first two sections that +show tracked paths: * ' ' = unmodified * 'M' = modified @@ -198,9 +213,6 @@ codes can be interpreted as follows: * 'C' = copied * 'U' = updated but unmerged -Ignored files are not listed, unless `--ignored` option is in effect, -in which case `XY` are `!!`. - .... X Y Meaning ------------------------------------------------- diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 1489cb09a0..2853f168d9 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -30,9 +30,8 @@ SYNOPSIS DESCRIPTION ----------- -Modifies the index or directory cache. Each file mentioned is updated -into the index and any 'unmerged' or 'needs updating' state is -cleared. +Modifies the index. Each file mentioned is updated into the index and +any 'unmerged' or 'needs updating' state is cleared. See also linkgit:git-add[1] for a more user-friendly way to do some of the most common operations on the index. diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index af06128cc9..f1bb1fa5f5 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -97,8 +97,9 @@ list:: List details of each working tree. The main working tree is listed first, followed by each of the linked working trees. The output details include whether the working tree is bare, the revision currently checked out, the -branch currently checked out (or "detached HEAD" if none), and "locked" if -the worktree is locked. +branch currently checked out (or "detached HEAD" if none), "locked" if +the worktree is locked, "prunable" if the worktree can be pruned by `prune` +command. lock:: @@ -143,6 +144,11 @@ locate it. Running `repair` within the recently-moved working tree will reestablish the connection. If multiple linked working trees are moved, running `repair` from any working tree with each tree's new `<path>` as an argument, will reestablish the connection to all the specified paths. ++ +If both the main working tree and linked working trees have been moved +manually, then running `repair` in the main working tree and specifying the +new `<path>` of each linked working tree will reestablish all connections +in both directions. unlock:: @@ -226,9 +232,14 @@ This can also be set up as the default behaviour by using the -v:: --verbose:: With `prune`, report all removals. ++ +With `list`, output additional information about worktrees (see below). --expire <time>:: With `prune`, only expire unused working trees older than `<time>`. ++ +With `list`, annotate missing working trees as prunable if they are +older than `<time>`. --reason <string>:: With `lock`, an explanation why the working tree is locked. @@ -367,13 +378,46 @@ $ git worktree list /path/to/other-linked-worktree 1234abc (detached HEAD) ------------ +The command also shows annotations for each working tree, according to its state. +These annotations are: + + * `locked`, if the working tree is locked. + * `prunable`, if the working tree can be pruned via `git worktree prune`. + +------------ +$ git worktree list +/path/to/linked-worktree abcd1234 [master] +/path/to/locked-worktreee acbd5678 (brancha) locked +/path/to/prunable-worktree 5678abc (detached HEAD) prunable +------------ + +For these annotations, a reason might also be available and this can be +seen using the verbose mode. The annotation is then moved to the next line +indented followed by the additional information. + +------------ +$ git worktree list --verbose +/path/to/linked-worktree abcd1234 [master] +/path/to/locked-worktree-no-reason abcd5678 (detached HEAD) locked +/path/to/locked-worktree-with-reason 1234abcd (brancha) + locked: working tree path is mounted on a portable device +/path/to/prunable-worktree 5678abc1 (detached HEAD) + prunable: gitdir file points to non-existent location +------------ + +Note that the annotation is moved to the next line if the additional +information is available, otherwise it stays on the same line as the +working tree itself. + Porcelain Format ~~~~~~~~~~~~~~~~ The porcelain format has a line per attribute. Attributes are listed with a label and value separated by a single space. Boolean attributes (like `bare` and `detached`) are listed as a label only, and are present only -if the value is true. The first attribute of a working tree is always -`worktree`, an empty line indicates the end of the record. For example: +if the value is true. Some attributes (like `locked`) can be listed as a label +only or with a value depending upon whether a reason is available. The first +attribute of a working tree is always `worktree`, an empty line indicates the +end of the record. For example: ------------ $ git worktree list --porcelain @@ -388,6 +432,33 @@ worktree /path/to/other-linked-worktree HEAD 1234abc1234abc1234abc1234abc1234abc1234a detached +worktree /path/to/linked-worktree-locked-no-reason +HEAD 5678abc5678abc5678abc5678abc5678abc5678c +branch refs/heads/locked-no-reason +locked + +worktree /path/to/linked-worktree-locked-with-reason +HEAD 3456def3456def3456def3456def3456def3456b +branch refs/heads/locked-with-reason +locked reason why is locked + +worktree /path/to/linked-worktree-prunable +HEAD 1233def1234def1234def1234def1234def1234b +detached +prunable gitdir file points to non-existent location + +------------ + +If the lock reason contains "unusual" characters such as newline, they +are escaped and the entire reason is quoted as explained for the +configuration variable `core.quotePath` (see linkgit:git-config[1]). +For Example: + +------------ +$ git worktree list --porcelain +... +locked "reason\nwhy is locked" +... ------------ EXAMPLES diff --git a/Documentation/git.txt b/Documentation/git.txt index a6d4ad0818..d36e6fd482 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -13,7 +13,7 @@ SYNOPSIS [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] [-p|--paginate|-P|--no-pager] [--no-replace-objects] [--bare] [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] - [--super-prefix=<path>] + [--super-prefix=<path>] [--config-env <name>=<envvar>] <command> [<args>] DESCRIPTION @@ -80,6 +80,28 @@ config file). Including the equals but with an empty value (like `git -c foo.bar= ...`) sets `foo.bar` to the empty string which `git config --type=bool` will convert to `false`. +--config-env=<name>=<envvar>:: + Like `-c <name>=<value>`, give configuration variable + '<name>' a value, where <envvar> is the name of an + environment variable from which to retrieve the value. Unlike + `-c` there is no shortcut for directly setting the value to an + empty string, instead the environment variable itself must be + set to the empty string. It is an error if the `<envvar>` does not exist + in the environment. `<envvar>` may not contain an equals sign + to avoid ambiguity with `<name>`s which contain one. ++ +This is useful for cases where you want to pass transitory +configuration options to git, but are doing so on OS's where +other processes might be able to read your cmdline +(e.g. `/proc/self/cmdline`), but not your environ +(e.g. `/proc/self/environ`). That behavior is the default on +Linux, but may not be on your system. ++ +Note that this might add security for variables such as +`http.extraHeader` where the sensitive information is part of +the value, but not e.g. `url.<base>.insteadOf` where the +sensitive information can be part of the key. + --exec-path[=<path>]:: Path to wherever your core Git programs are installed. This can also be controlled by setting the GIT_EXEC_PATH diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index ffccfc7760..1f3b57d04d 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -644,7 +644,7 @@ changelist text. Exiting with a non-zero status from the script will abort the process. The purpose of the hook is to edit the message file in place, -and it is not supressed by the `--no-verify` option. This hook +and it is not suppressed by the `--no-verify` option. This hook is called even if `--prepare-p4-only` is set. Run `git-p4 submit --help` for details. diff --git a/Documentation/gitmailmap.txt b/Documentation/gitmailmap.txt new file mode 100644 index 0000000000..052209b33b --- /dev/null +++ b/Documentation/gitmailmap.txt @@ -0,0 +1,123 @@ +gitmailmap(5) +============= + +NAME +---- +gitmailmap - Map author/committer names and/or E-Mail addresses + +SYNOPSIS +-------- +$GIT_WORK_TREE/.mailmap + + +DESCRIPTION +----------- + +If the file `.mailmap` exists at the toplevel of the repository, or at +the location pointed to by the `mailmap.file` or `mailmap.blob` +configuration options (see linkgit:git-config[1]), it +is used to map author and committer names and email addresses to +canonical real names and email addresses. + + +SYNTAX +------ + +The '#' character begins a comment to the end of line, blank lines +are ignored. + +In the simple form, each line in the file consists of the canonical +real name of an author, whitespace, and an email address used in the +commit (enclosed by '<' and '>') to map to the name. For example: +-- + Proper Name <commit@email.xx> +-- + +The more complex forms are: +-- + <proper@email.xx> <commit@email.xx> +-- +which allows mailmap to replace only the email part of a commit, and: +-- + Proper Name <proper@email.xx> <commit@email.xx> +-- +which allows mailmap to replace both the name and the email of a +commit matching the specified commit email address, and: +-- + Proper Name <proper@email.xx> Commit Name <commit@email.xx> +-- +which allows mailmap to replace both the name and the email of a +commit matching both the specified commit name and email address. + +Both E-Mails and names are matched case-insensitively. For example +this would also match the 'Commit Name <commit@email.xx>' above: +-- +Proper Name <proper@email.xx> CoMmIt NaMe <CoMmIt@EmAiL.xX> +-- + +EXAMPLES +-------- + +Your history contains commits by two authors, Jane +and Joe, whose names appear in the repository under several forms: + +------------ +Joe Developer <joe@example.com> +Joe R. Developer <joe@example.com> +Jane Doe <jane@example.com> +Jane Doe <jane@laptop.(none)> +Jane D. <jane@desktop.(none)> +------------ + +Now suppose that Joe wants his middle name initial used, and Jane +prefers her family name fully spelled out. A `.mailmap` file to +correct the names would look like: + +------------ +Joe R. Developer <joe@example.com> +Jane Doe <jane@example.com> +Jane Doe <jane@desktop.(none)> +------------ + +Note that there's no need to map the name for 'jane@laptop.(none)' to +only correct the names. However, leaving the obviously broken +`<jane@laptop.(none)>' and '<jane@desktop.(none)>' E-Mails as-is is +usually not what you want. A `.mailmap` file which also corrects those +is: + +------------ +Joe R. Developer <joe@example.com> +Jane Doe <jane@example.com> <jane@laptop.(none)> +Jane Doe <jane@example.com> <jane@desktop.(none)> +------------ + +Finally, let's say that Joe and Jane shared an E-Mail address, but not +a name, e.g. by having these two commits in the history generated by a +bug reporting system. I.e. names appearing in history as: + +------------ +Joe <bugs@example.com> +Jane <bugs@example.com> +------------ + +A full `.mailmap` file which also handles those cases (an addition of +two lines to the above example) would be: + +------------ +Joe R. Developer <joe@example.com> +Jane Doe <jane@example.com> <jane@laptop.(none)> +Jane Doe <jane@example.com> <jane@desktop.(none)> +Joe R. Developer <joe@example.com> Joe <bugs@example.com> +Jane Doe <jane@example.com> Jane <bugs@example.com> +------------ + + + +SEE ALSO +-------- +linkgit:git-check-mailmap[1] + + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 539b4e1997..8e333dde1b 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -7,7 +7,7 @@ gitmodules - Defining submodule properties SYNOPSIS -------- -$GIT_WORK_DIR/.gitmodules +$GIT_WORK_TREE/.gitmodules DESCRIPTION @@ -27,19 +27,19 @@ submodule.<name>.path:: Defines the path, relative to the top-level directory of the Git working tree, where the submodule is expected to be checked out. The path name must not end with a `/`. All submodule paths must - be unique within the .gitmodules file. + be unique within the `.gitmodules` file. submodule.<name>.url:: Defines a URL from which the submodule repository can be cloned. This may be either an absolute URL ready to be passed to - linkgit:git-clone[1] or (if it begins with ./ or ../) a location + linkgit:git-clone[1] or (if it begins with `./` or `../`) a location relative to the superproject's origin repository. In addition, there are a number of optional keys: submodule.<name>.update:: Defines the default update procedure for the named submodule, - i.e. how the submodule is updated by "git submodule update" + i.e. how the submodule is updated by the `git submodule update` command in the superproject. This is only used by `git submodule init` to initialize the configuration variable of the same name. Allowed values here are 'checkout', 'rebase', @@ -49,7 +49,7 @@ submodule.<name>.update:: submodule.<name>.branch:: A remote branch name for tracking updates in the upstream submodule. - If the option is not specified, it defaults to the remote 'HEAD'. + If the option is not specified, it defaults to the remote `HEAD`. A special value of `.` is used to indicate that the name of the branch in the submodule should be the same name as the current branch in the current repository. See the `--remote` documentation in @@ -57,14 +57,14 @@ submodule.<name>.branch:: submodule.<name>.fetchRecurseSubmodules:: This option can be used to control recursive fetching of this - submodule. If this option is also present in the submodules entry in - .git/config of the superproject, the setting there will override the - one found in .gitmodules. + submodule. If this option is also present in the submodule's entry in + `.git/config` of the superproject, the setting there will override the + one found in `.gitmodules`. Both settings can be overridden on the command line by using the - "--[no-]recurse-submodules" option to "git fetch" and "git pull". + `--[no-]recurse-submodules` option to `git fetch` and `git pull`. submodule.<name>.ignore:: - Defines under what circumstances "git status" and the diff family show + Defines under what circumstances `git status` and the diff family show a submodule as modified. The following values are supported: + -- @@ -73,7 +73,7 @@ submodule.<name>.ignore:: been staged). dirty;; All changes to the submodule's work tree will be ignored, only - committed differences between the HEAD of the submodule and its + committed differences between the `HEAD` of the submodule and its recorded state in the superproject are taken into account. untracked;; Only untracked files in submodules will be ignored. @@ -84,12 +84,12 @@ submodule.<name>.ignore:: differences, and modifications to tracked and untracked files are shown. This is the default option. -If this option is also present in the submodules entry in .git/config +If this option is also present in the submodule's entry in `.git/config` of the superproject, the setting there will override the one found in -.gitmodules. +`.gitmodules`. Both settings can be overridden on the command line by using the -"--ignore-submodules" option. The 'git submodule' commands are not +`--ignore-submodules` option. The `git submodule` commands are not affected by this setting. -- @@ -102,7 +102,7 @@ submodule.<name>.shallow:: EXAMPLES -------- -Consider the following .gitmodules file: +Consider the following `.gitmodules` file: ---- [submodule "libfoo"] diff --git a/Documentation/mailmap.txt b/Documentation/mailmap.txt deleted file mode 100644 index 4a8c276529..0000000000 --- a/Documentation/mailmap.txt +++ /dev/null @@ -1,75 +0,0 @@ -If the file `.mailmap` exists at the toplevel of the repository, or at -the location pointed to by the mailmap.file or mailmap.blob -configuration options, it -is used to map author and committer names and email addresses to -canonical real names and email addresses. - -In the simple form, each line in the file consists of the canonical -real name of an author, whitespace, and an email address used in the -commit (enclosed by '<' and '>') to map to the name. For example: --- - Proper Name <commit@email.xx> --- - -The more complex forms are: --- - <proper@email.xx> <commit@email.xx> --- -which allows mailmap to replace only the email part of a commit, and: --- - Proper Name <proper@email.xx> <commit@email.xx> --- -which allows mailmap to replace both the name and the email of a -commit matching the specified commit email address, and: --- - Proper Name <proper@email.xx> Commit Name <commit@email.xx> --- -which allows mailmap to replace both the name and the email of a -commit matching both the specified commit name and email address. - -Example 1: Your history contains commits by two authors, Jane -and Joe, whose names appear in the repository under several forms: - ------------- -Joe Developer <joe@example.com> -Joe R. Developer <joe@example.com> -Jane Doe <jane@example.com> -Jane Doe <jane@laptop.(none)> -Jane D. <jane@desktop.(none)> ------------- - -Now suppose that Joe wants his middle name initial used, and Jane -prefers her family name fully spelled out. A proper `.mailmap` file -would look like: - ------------- -Jane Doe <jane@desktop.(none)> -Joe R. Developer <joe@example.com> ------------- - -Note how there is no need for an entry for `<jane@laptop.(none)>`, because the -real name of that author is already correct. - -Example 2: Your repository contains commits from the following -authors: - ------------- -nick1 <bugs@company.xx> -nick2 <bugs@company.xx> -nick2 <nick2@company.xx> -santa <me@company.xx> -claus <me@company.xx> -CTO <cto@coompany.xx> ------------- - -Then you might want a `.mailmap` file that looks like: ------------- -<cto@company.xx> <cto@coompany.xx> -Some Dude <some@dude.xx> nick1 <bugs@company.xx> -Other Author <other@author.xx> nick2 <bugs@company.xx> -Other Author <other@author.xx> <nick2@company.xx> -Santa Claus <santa.claus@northpole.xx> <me@company.xx> ------------- - -Use hash '#' for comments that are either on their own line, or after -the email address. diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 84bbc7439a..6b59e28d44 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -252,7 +252,15 @@ endif::git-rev-list[] interpreted by linkgit:git-interpret-trailers[1]. The `trailers` string may be followed by a colon - and zero or more comma-separated options: + and zero or more comma-separated options. + If any option is provided multiple times the + last occurance wins. ++ +The boolean options accept an optional value `[=<BOOL>]`. The values +`true`, `false`, `on`, `off` etc. are all accepted. See the "boolean" +sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean +option is given with no value, it's enabled. ++ ** 'key=<K>': only show trailers with specified key. Matching is done case-insensitively and trailing colon is optional. If option is given multiple times trailer lines matching any of the keys are @@ -261,27 +269,25 @@ endif::git-rev-list[] desired it can be disabled with `only=false`. E.g., `%(trailers:key=Reviewed-by)` shows trailer lines with key `Reviewed-by`. -** 'only[=val]': select whether non-trailer lines from the trailer - block should be included. The `only` keyword may optionally be - followed by an equal sign and one of `true`, `on`, `yes` to omit or - `false`, `off`, `no` to show the non-trailer lines. If option is - given without value it is enabled. If given multiple times the last - value is used. +** 'only[=<BOOL>]': select whether non-trailer lines from the trailer + block should be included. ** 'separator=<SEP>': specify a separator inserted between trailer lines. When this option is not given each trailer line is terminated with a line feed character. The string SEP may contain the literal formatting codes described above. To use comma as separator one must use `%x2C` as it would otherwise be parsed as - next option. If separator option is given multiple times only the - last one is used. E.g., `%(trailers:key=Ticket,separator=%x2C )` + next option. E.g., `%(trailers:key=Ticket,separator=%x2C )` shows all trailer lines whose key is "Ticket" separated by a comma and a space. -** 'unfold[=val]': make it behave as if interpret-trailer's `--unfold` - option was given. In same way as to for `only` it can be followed - by an equal sign and explicit value. E.g., +** 'unfold[=<BOOL>]': make it behave as if interpret-trailer's `--unfold` + option was given. E.g., `%(trailers:only,unfold=true)` unfolds and shows all trailer lines. -** 'valueonly[=val]': skip over the key part of the trailer line and only - show the value part. Also this optionally allows explicit value. +** 'keyonly[=<BOOL>]': only show the key part of the trailer. +** 'valueonly[=<BOOL>]': only show the value part of the trailer. +** 'key_value_separator=<SEP>': specify a separator inserted between + trailer lines. When this option is not given each trailer key-value + pair is separated by ": ". Otherwise it shares the same semantics + as 'separator=<SEP>' above. NOTE: Some placeholders may depend on other options given to the revision traversal engine. For example, the `%g*` reflog options will diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 002379056a..96cc89d157 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -130,6 +130,11 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit). this option allows you to ignore the individual commits brought in to your history by such a merge. +ifdef::git-log[] + This option also changes default diff format for merge commits + to `first-parent`, see `--diff-merges=first-parent` for details. +endif::git-log[] + --not:: Reverses the meaning of the '{caret}' prefix (or lack thereof) for all following revision specifiers, up to the next `--not`. diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index f96b2e605f..96d2fc589f 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -55,6 +55,18 @@ Valid object types are: Type 5 is reserved for future expansion. Type 0 is invalid. +=== Size encoding + +This document uses the following "size encoding" of non-negative +integers: From each byte, the seven least significant bits are +used to form the resulting integer. As long as the most significant +bit is 1, this process continues; the byte with MSB 0 provides the +last seven bits. The seven-bit chunks are concatenated. Later +values are more significant. + +This size encoding should not be confused with the "offset encoding", +which is also used in this document. + === Deltified representation Conceptually there are only four object types: commit, tree, tag and @@ -73,7 +85,10 @@ Ref-delta can also refer to an object outside the pack (i.e. the so-called "thin pack"). When stored on disk however, the pack should be self contained to avoid cyclic dependency. -The delta data is a sequence of instructions to reconstruct an object +The delta data starts with the size of the base object and the +size of the object to be reconstructed. These sizes are +encoded using the size encoding from above. The remainder of +the delta data is a sequence of instructions to reconstruct the object from the base object. If the base object is deltified, it must be converted to canonical form first. Each instruction appends more and more data to the target object until it's complete. There are two diff --git a/Documentation/technical/packfile-uri.txt b/Documentation/technical/packfile-uri.txt index 318713abc3..f7eabc6c76 100644 --- a/Documentation/technical/packfile-uri.txt +++ b/Documentation/technical/packfile-uri.txt @@ -37,8 +37,11 @@ at least so that we can test the client. This is the implementation: a feature, marked experimental, that allows the server to be configured by one or more `uploadpack.blobPackfileUri=<sha1> <uri>` entries. Whenever the list of objects to be sent is assembled, all such -blobs are excluded, replaced with URIs. The client will download those URIs, -expecting them to each point to packfiles containing single blobs. +blobs are excluded, replaced with URIs. As noted in "Future work" below, the +server can evolve in the future to support excluding other objects (or other +implementations of servers could be made that support excluding other objects) +without needing a protocol change, so clients should not expect that packfiles +downloaded in this way only contain single blobs. Client design ------------- diff --git a/Documentation/technical/reftable.txt b/Documentation/technical/reftable.txt index 2951840e9c..8095ab2590 100644 --- a/Documentation/technical/reftable.txt +++ b/Documentation/technical/reftable.txt @@ -446,7 +446,7 @@ especially if readers will not use the object name to ref mapping. Object blocks use unique, abbreviated 2-32 object name keys, mapping to ref blocks containing references pointing to that object directly, or as the peeled value of an annotated tag. Like ref blocks, object blocks use -the file's standard block size. The abbrevation length is available in +the file's standard block size. The abbreviation length is available in the footer as `obj_id_len`. To save space in small files, object blocks may be omitted if the ref |