diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes/2.25.2.txt | 60 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.26.0.txt | 106 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.27.0.txt | 41 | ||||
| -rw-r--r-- | Documentation/config.txt | 2 | ||||
| -rw-r--r-- | Documentation/config/http.txt | 21 | ||||
| -rw-r--r-- | Documentation/config/tag.txt | 7 | ||||
| -rw-r--r-- | Documentation/config/tar.txt | 6 | ||||
| -rw-r--r-- | Documentation/fetch-options.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-am.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-fast-import.txt | 20 | ||||
| -rw-r--r-- | Documentation/git-init.txt | 7 | ||||
| -rw-r--r-- | Documentation/git-ls-remote.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-rebase.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-rm.txt | 61 | ||||
| -rw-r--r-- | Documentation/git-stash.txt | 144 | ||||
| -rw-r--r-- | Documentation/git.txt | 6 | ||||
| -rw-r--r-- | Documentation/gitcli.txt | 5 | ||||
| -rw-r--r-- | Documentation/howto/maintain-git.txt | 52 |
18 files changed, 451 insertions, 121 deletions
diff --git a/Documentation/RelNotes/2.25.2.txt b/Documentation/RelNotes/2.25.2.txt new file mode 100644 index 0000000000..303c53a17f --- /dev/null +++ b/Documentation/RelNotes/2.25.2.txt @@ -0,0 +1,60 @@ +Git 2.25.2 Release Notes +======================== + +Fixes since v2.25.1 +------------------- + + * Minor bugfixes to "git add -i" that has recently been rewritten in C. + + * An earlier update to show the location of working tree in the error + message did not consider the possibility that a git command may be + run in a bare repository, which has been corrected. + + * The "--recurse-submodules" option of various subcommands did not + work well when run in an alternate worktree, which has been + corrected. + + * Running "git rm" on a submodule failed unnecessarily when + .gitmodules is only cache-dirty, which has been corrected. + + * "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. + + * 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. + + * The code to automatically shrink the fan-out in the notes tree had + an off-by-one bug, which has been killed. + + * "git check-ignore" did not work when the given path is explicitly + marked as not ignored with a negative entry in the .gitignore file. + + * The merge-recursive machinery failed to refresh the cache entry for + a merge result in a couple of places, resulting in an unnecessary + merge failure, which has been fixed. + + * Fix for a bug revealed by a recent change to make the protocol v2 + the default. + + * "git merge signed-tag" while lacking the public key started to say + "No signature", which was utterly wrong. This regression has been + reverted. + + * MinGW's poll() emulation has been improved. + + * "git show" and others gave an object name in raw format in its + error output, which has been corrected to give it in hex. + + * Both "git ls-remote -h" and "git grep -h" give short usage help, + like any other Git subcommand, but it is not unreasonable to expect + that the former would behave the same as "git ls-remote --head" + (there is no other sensible behaviour for the latter). The + documentation has been updated in an attempt to clarify this. + +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 index 30ef134eec..3a7a734c26 100644 --- a/Documentation/RelNotes/2.26.0.txt +++ b/Documentation/RelNotes/2.26.0.txt @@ -4,6 +4,19 @@ Git 2.26 Release Notes Updates since v2.25 ------------------- +Backward compatibility notes + + * "git rebase" uses a different backend that is based on the 'merge' + machinery by default. There are a few known differences in the + behaviour from the traditional machinery based on patch+apply. + + If your workflow is negatively affected by this change, please + report it to git@vger.kernel.org so that we can take a look into + it. After doing so, you can set the 'rebase.backend' configuration + variable to 'apply', in order to use the old default behaviour in + the meantime. + + UI, Workflows & Features * Sample credential helper for using .netrc has been updated to work @@ -38,6 +51,27 @@ UI, Workflows & Features * The basic 7 colors learned the brighter counterparts (e.g. "brightred"). + * "git sparse-checkout" learned a new "add" subcommand. + + * A configuration element used for credential subsystem can now use + wildcard pattern to specify for which set of URLs the entry + applies. + + * "git clone --recurse-submodules --single-branch" now uses the same + single-branch option when cloning the submodules. + + * "git rm" and "git stash" learns the new "--pathspec-from-file" + option. + + * "git am --show-current-patch" is a way to show the piece of e-mail + for the stopped step, which is not suitable to directly feed "git + apply" (it is designed to be a good "git am" input). It learned a + new option to show only the patch part. + + * Handling of conflicting renames in merge-recursive have further + been made consistent with how existing codepaths try to mimic what + is done to add/add conflicts. + Performance, Internal Implementation, Development Support etc. @@ -45,7 +79,7 @@ Performance, Internal Implementation, Development Support etc. with tabs. * The test-lint machinery knew to check "VAR=VAL shell_function" - construct, but did not check "VAR= shell_funciton", which has been + construct, but did not check "VAR= shell_function", which has been corrected. * Replace "git config --bool" calls with "git config --type=bool" in @@ -108,6 +142,9 @@ Performance, Internal Implementation, Development Support etc. equivalent of "format-patch piped to am"). The rebase.backend configuration variable can be set to customize. + * Underlying machinery of "git bisect--helper" is being refactored + into pieces that are more easily reused. + Fixes since v2.25 ----------------- @@ -151,7 +188,6 @@ Fixes since v2.25 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. @@ -174,17 +210,14 @@ Fixes since v2.25 * 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 @@ -196,12 +229,11 @@ Fixes since v2.25 * 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 + their abbreviated object name, which could become ambiguous 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. @@ -215,13 +247,12 @@ Fixes since v2.25 * 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 @@ -233,26 +264,60 @@ Fixes since v2.25 branch.<name>.pushRemote is now also updated. * Update to doc-diff. - (merge 2607d39da3 jk/doc-diff-parallel later to maint). * Doc markup fix. - (merge 0aa6ce3094 jk/push-option-doc-markup-fix later to maint). * "git check-ignore" did not work when the given path is explicitly marked as not ignored with a negative entry in the .gitignore file. - (merge 7ec8125fba en/check-ignore later to maint). * The merge-recursive machinery failed to refresh the cache entry for a merge result in a couple of places, resulting in an unnecessary merge failure, which has been fixed. - (merge fb1c18fc46 en/t3433-rebase-stat-dirty-failure later to maint). * Fix for a bug revealed by a recent change to make the protocol v2 the default. - (merge 3e96c66805 ds/partial-clone-fixes later to maint). + + * In rare cases "git worktree add <path>" could think that <path> + was already a registered worktree even when it wasn't and refuse + to add the new worktree. This has been corrected. + (merge bb69b3b009 es/worktree-avoid-duplication-fix later to maint). + + * "git push" should stop from updating a branch that is checked out + when receive.denyCurrentBranch configuration is set, but it failed + to pay attention to checkouts in secondary worktrees. This has + been corrected. + (merge 4d864895a2 hv/receive-denycurrent-everywhere later to maint). + + * "git rebase BASE BRANCH" rebased/updated the tip of BRANCH and + checked it out, even when the BRANCH is checked out in a different + worktree. This has been corrected. + (merge b5cabb4a96 es/do-not-let-rebase-switch-to-protected-branch later to maint). + + * "git describe" in a repository with multiple root commits sometimes + gave up looking for the best tag to describe a given commit with + too early, which has been adjusted. + + * "git merge signed-tag" while lacking the public key started to say + "No signature", which was utterly wrong. This regression has been + reverted. + + * MinGW's poll() emulation has been improved. + + * "git show" and others gave an object name in raw format in its + error output, which has been corrected to give it in hex. + + * "git fetch" over HTTP walker protocol did not show any progress + output. We inherently do not know how much work remains, but still + we can show something not to bore users. + (merge 7655b4119d rs/show-progress-in-dumb-http-fetch later to maint). + + * Both "git ls-remote -h" and "git grep -h" give short usage help, + like any other Git subcommand, but it is not unreasonable to expect + that the former would behave the same as "git ls-remote --head" + (there is no other sensible behaviour for the latter). The + documentation has been updated in an attempt to clarify this. * 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). @@ -263,15 +328,14 @@ Fixes since v2.25 (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). - (merge 539052f42f jk/run-command-formatfix later to maint). (merge 02bbbe9df9 es/worktree-cleanup later to maint). (merge 2ce6d075fa rs/micro-cleanups later to maint). (merge 27f182b3fc rs/blame-typefix-for-fingerprint later to maint). (merge 3c29e21eb0 ma/test-cleanup later to maint). + (merge 240fc04f81 ag/rebase-remove-redundant-code later to maint). + (merge d68ce906c7 rs/commit-graph-code-simplification later to maint). + (merge a51d9e8f07 rj/t1050-use-test-path-is-file later to maint). + (merge fd0bc17557 kk/complete-diff-color-moved later to maint). + (merge 65bf820d0e en/test-cleanup later to maint). diff --git a/Documentation/RelNotes/2.27.0.txt b/Documentation/RelNotes/2.27.0.txt new file mode 100644 index 0000000000..84eab736a2 --- /dev/null +++ b/Documentation/RelNotes/2.27.0.txt @@ -0,0 +1,41 @@ +Git 2.27 Release Notes +====================== + +Updates since v2.26 +------------------- + +UI, Workflows & Features + + * A handful of options to configure SSL when talking to proxies have + been added. + + +Performance, Internal Implementation, Development Support etc. + + * The advise API has been revamped to allow more systematic enumeration of + advice knobs in the future. + + +Fixes since v2.26 +----------------- + + * The real_path() convenience function can easily be misused; with a + bit of code refactoring in the callers' side, its use has been + eliminated. + (merge 49d3c4b481 am/real-path-fix later to maint). + + * Update "git p4" to work with Python 3. + (merge 6bb40ed20a yz/p4-py3 later to maint). + + * The mechanism to prevent "git commit" from making an empty commit + or amending during an interrupted cherry-pick was broken during the + rewrite of "git rebase" in C, which has been corrected. + (merge 430b75f720 pw/advise-rebase-skip later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 564956f358 jc/maintain-doc later to maint). + (merge 7422b2a0a1 sg/commit-slab-clarify-peek later to maint). + (merge 9c688735f6 rs/doc-passthru-fetch-options later to maint). + (merge 757c2ba3e2 en/oidset-uninclude-hashmap later to maint). + (merge 8312aa7d74 jc/config-tar later to maint). + (merge d00a5bdd50 ss/submodule-foreach-cb later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index 08b13ba72b..2450589a0e 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -447,6 +447,8 @@ include::config/submodule.txt[] include::config/tag.txt[] +include::config/tar.txt[] + include::config/trace2.txt[] include::config/transfer.txt[] diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt index e806033aab..3968fbb697 100644 --- a/Documentation/config/http.txt +++ b/Documentation/config/http.txt @@ -29,6 +29,27 @@ http.proxyAuthMethod:: * `ntlm` - NTLM authentication (compare the --ntlm option of `curl(1)`) -- +http.proxySSLCert:: + The pathname of a file that stores a client certificate to use to authenticate + with an HTTPS proxy. Can be overridden by the `GIT_PROXY_SSL_CERT` environment + variable. + +http.proxySSLKey:: + The pathname of a file that stores a private key to use to authenticate with + an HTTPS proxy. Can be overridden by the `GIT_PROXY_SSL_KEY` environment + variable. + +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` + 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 + `GIT_PROXY_SSL_CAINFO` environment variable. + http.emptyAuth:: Attempt authentication without seeking a username or password. This can be used to attempt GSS-Negotiate authentication without specifying diff --git a/Documentation/config/tag.txt b/Documentation/config/tag.txt index 6d9110d84c..5062a057ff 100644 --- a/Documentation/config/tag.txt +++ b/Documentation/config/tag.txt @@ -15,10 +15,3 @@ tag.gpgSign:: convenient to use an agent to avoid typing your gpg passphrase several times. Note that this option doesn't affect tag signing behavior enabled by "-u <keyid>" or "--local-user=<keyid>" options. - -tar.umask:: - This variable can be used to restrict the permission bits of - tar archive entries. The default is 0002, which turns off the - world write bit. The special value "user" indicates that the - archiving user's umask will be used instead. See umask(2) and - linkgit:git-archive[1]. diff --git a/Documentation/config/tar.txt b/Documentation/config/tar.txt new file mode 100644 index 0000000000..de8ff48ea9 --- /dev/null +++ b/Documentation/config/tar.txt @@ -0,0 +1,6 @@ +tar.umask:: + This variable can be used to restrict the permission bits of + tar archive entries. The default is 0002, which turns off the + world write bit. The special value "user" indicates that the + archiving user's umask will be used instead. See umask(2) and + linkgit:git-archive[1]. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index a115a1ae0e..00d03ec8c3 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -61,10 +61,8 @@ this option multiple times, one for each matching ref name. See also the `fetch.negotiationAlgorithm` configuration variable documented in linkgit:git-config[1]. -ifndef::git-pull[] --dry-run:: Show what would be done, without making any changes. -endif::git-pull[] -f:: --force:: @@ -95,6 +93,7 @@ ifndef::git-pull[] --[no-]write-commit-graph:: Write a commit-graph after fetching. This overrides the config setting `fetch.writeCommitGraph`. +endif::git-pull[] -p:: --prune:: @@ -107,6 +106,7 @@ ifndef::git-pull[] was cloned with the --mirror option), then they are also subject to pruning. Supplying `--prune-tags` is a shorthand for providing the tag refspec. +ifndef::git-pull[] + See the PRUNING section below for more details. @@ -133,7 +133,6 @@ endif::git-pull[] behavior for a remote may be specified with the remote.<name>.tagOpt setting. See linkgit:git-config[1]. -ifndef::git-pull[] --refmap=<refspec>:: When fetching refs listed on the command line, use the specified refspec (can be given more than once) to map the @@ -154,6 +153,7 @@ ifndef::git-pull[] is used (though tags may be pruned anyway if they are also the destination of an explicit refspec; see `--prune`). +ifndef::git-pull[] --recurse-submodules[=yes|on-demand|no]:: This option controls if and under what conditions new commits of populated submodules should be fetched too. It can be used as a @@ -164,6 +164,7 @@ ifndef::git-pull[] when the superproject retrieves a commit that updates the submodule's reference to a commit that isn't already in the local submodule clone. +endif::git-pull[] -j:: --jobs=<n>:: @@ -177,9 +178,11 @@ parallel. To control them independently, use the config settings Typically, parallel recursive and multi-remote fetches will be faster. By default fetches are performed sequentially, not in parallel. +ifndef::git-pull[] --no-recurse-submodules:: Disable recursive fetching of submodules (this has the same effect as using the `--recurse-submodules=no` option). +endif::git-pull[] --set-upstream:: If the remote is fetched successfully, pull and add upstream @@ -188,6 +191,7 @@ default fetches are performed sequentially, not in parallel. see `branch.<name>.merge` and `branch.<name>.remote` in linkgit:git-config[1]. +ifndef::git-pull[] --submodule-prefix=<path>:: Prepend <path> to paths printed in informative messages such as "Fetching submodule foo". This option is used diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 11ca61b00b..ab5754e05d 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -16,7 +16,7 @@ SYNOPSIS [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet] [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>] [(<mbox> | <Maildir>)...] -'git am' (--continue | --skip | --abort | --quit | --show-current-patch) +'git am' (--continue | --skip | --abort | --quit | --show-current-patch[=(diff|raw)]) DESCRIPTION ----------- @@ -176,9 +176,11 @@ default. You can use `--no-utf8` to override this. Abort the patching operation but keep HEAD and the index untouched. ---show-current-patch:: - Show the entire e-mail message "git am" has stopped at, because - of conflicts. +--show-current-patch[=(diff|raw)]:: + Show the message at which `git am` has stopped due to + conflicts. If `raw` is specified, show the raw contents of + the e-mail message; if `diff`, show the diff portion only. + Defaults to `raw`. DISCUSSION ---------- diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 7889f95940..77c6b3d001 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -122,6 +122,26 @@ Locations of Marks Files Relative and non-relative marks may be combined by interweaving --(no-)-relative-marks with the --(import|export)-marks= options. +Submodule Rewriting +~~~~~~~~~~~~~~~~~~~ + +--rewrite-submodules-from=<name>:<file>:: +--rewrite-submodules-to=<name>:<file>:: + Rewrite the object IDs for the submodule specified by <name> from the values + used in the from <file> to those used in the to <file>. The from marks should + have been created by `git fast-export`, and the to marks should have been + created by `git fast-import` when importing that same submodule. ++ +<name> may be any arbitrary string not containing a colon character, but the +same value must be used with both options when specifying corresponding marks. +Multiple submodules may be specified with different values for <name>. It is an +error not to use these options in corresponding pairs. ++ +These options are primarily useful when converting a repository from one hash +algorithm to another; without them, fast-import will fail if it encounters a +submodule because it has no way of writing the object ID into the new hash +algorithm. + Performance and Compression Tuning ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 32880aafb0..adc6adfd38 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git init' [-q | --quiet] [--bare] [--template=<template_directory>] - [--separate-git-dir <git dir>] + [--separate-git-dir <git dir>] [--object-format=<format] [--shared[=<permissions>]] [directory] @@ -48,6 +48,11 @@ Only print error and warning messages; all other output will be suppressed. Create a bare repository. If `GIT_DIR` environment is not set, it is set to the current working directory. +--object-format=<format>:: + +Specify the given object format (hash algorithm) for the repository. The valid +values are 'sha1' and (if enabled) 'sha256'. 'sha1' is the default. + --template=<template_directory>:: Specify the directory from which templates will be used. (See the "TEMPLATE diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index a2ea1fd687..0a5c8b7d49 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -28,7 +28,9 @@ OPTIONS Limit to only refs/heads and refs/tags, respectively. These options are _not_ mutually exclusive; when given both, references stored in refs/heads and refs/tags are - displayed. + displayed. Note that `git ls-remote -h` used without + anything else on the command line gives help, consistent + with other git subcommands. --refs:: Do not show peeled tags or pseudorefs like `HEAD` in the output. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 8c1f4b8268..f7a6033607 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -699,6 +699,16 @@ suffer from the same shortcoming. (See https://lore.kernel.org/git/20200207132152.GC2868@szeder.dev/ for details.) +Commit Rewording +~~~~~~~~~~~~~~~~ + +When a conflict occurs while rebasing, rebase stops and asks the user +to resolve. Since the user may need to make notable changes while +resolving conflicts, after conflicts are resolved and the user has run +`git rebase --continue`, the rebase should open an editor and ask the +user to update the commit message. The merge backend does this, while +the apply backend blindly applies the original commit message. + Miscellaneous differences ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index b5c46223c4..ab750367fd 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -8,16 +8,18 @@ git-rm - Remove files from the working tree and from the index SYNOPSIS -------- [verse] -'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] [--quiet] [--] <file>... +'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] + [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]] + [--] [<pathspec>...] DESCRIPTION ----------- -Remove files from the index, or from the working tree and the index. -`git rm` will not remove a file from just your working directory. -(There is no option to remove a file only from the working tree -and yet keep it in the index; use `/bin/rm` if you want to do that.) -The files being removed have to be identical to the tip of the branch, -and no updates to their contents can be staged in the index, +Remove files matching pathspec from the index, or from the working tree +and the index. `git rm` will not remove a file from just your working +directory. (There is no option to remove a file only from the working +tree and yet keep it in the index; use `/bin/rm` if you want to do +that.) The files being removed have to be identical to the tip of the +branch, and no updates to their contents can be staged in the index, though that default behavior can be overridden with the `-f` option. When `--cached` is given, the staged content has to match either the tip of the branch or the file on disk, @@ -26,15 +28,20 @@ allowing the file to be removed from just the index. OPTIONS ------- -<file>...:: - Files to remove. Fileglobs (e.g. `*.c`) can be given to - remove all matching files. If you want Git to expand - file glob characters, you may need to shell-escape them. - A leading directory name - (e.g. `dir` to remove `dir/file1` and `dir/file2`) can be - given to remove all files in the directory, and recursively - all sub-directories, - but this requires the `-r` option to be explicitly given. +<pathspec>...:: + Files to remove. A leading directory name (e.g. `dir` to remove + `dir/file1` and `dir/file2`) can be given to remove all files in + the directory, and recursively all sub-directories, but this + requires the `-r` option to be explicitly given. ++ +The command removes only the paths that are known to Git. ++ +File globbing matches across directory boundaries. Thus, given two +directories `d` and `d2`, there is a difference between using +`git rm 'd*'` and `git rm 'd/*'`, as the former will also remove all +of directory `d2`. ++ +For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. -f:: --force:: @@ -68,19 +75,19 @@ OPTIONS `git rm` normally outputs one line (in the form of an `rm` command) for each file removed. This option suppresses that output. +--pathspec-from-file=<file>:: + Pathspec is passed in `<file>` instead of commandline args. If + `<file>` is exactly `-` then standard input is used. Pathspec + elements are separated by LF or CR/LF. Pathspec elements can be + quoted as explained for the configuration variable `core.quotePath` + (see linkgit:git-config[1]). See also `--pathspec-file-nul` and + global `--literal-pathspecs`. -DISCUSSION ----------- - -The <file> list given to the command can be exact pathnames, -file glob patterns, or leading directory names. The command -removes only the paths that are known to Git. Giving the name of -a file that you have not told Git about does not remove that file. +--pathspec-file-nul:: + Only meaningful with `--pathspec-from-file`. Pathspec elements are + separated with NUL character and all other characters are taken + literally (including newlines and quotes). -File globbing matches across directory boundaries. Thus, given -two directories `d` and `d2`, there is a difference between -using `git rm 'd*'` and `git rm 'd/*'`, as the former will -also remove all of directory `d2`. REMOVING FILES THAT HAVE DISAPPEARED FROM THE FILESYSTEM -------------------------------------------------------- diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 53e1a1205d..31f1beb65b 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -15,6 +15,7 @@ SYNOPSIS 'git stash' branch <branchname> [<stash>] 'git stash' [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] [-u|--include-untracked] [-a|--all] [-m|--message <message>] + [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]] 'git stash' clear 'git stash' create [<message>] @@ -43,10 +44,10 @@ created stash, `stash@{1}` is the one before it, `stash@{2.hours.ago}` is also possible). Stashes may also be referenced by specifying just the stash index (e.g. the integer `n` is equivalent to `stash@{n}`). -OPTIONS -------- +COMMANDS +-------- -push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--] [<pathspec>...]:: +push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]:: Save your local modifications to a new 'stash entry' and roll them back to HEAD (in the working tree and in the index). @@ -56,38 +57,13 @@ push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q For quickly making a snapshot, you can omit "push". In this mode, non-option arguments are not allowed to prevent a misspelled subcommand from making an unwanted stash entry. The two exceptions to this -are `stash -p` which acts as alias for `stash push -p` and pathspecs, +are `stash -p` which acts as alias for `stash push -p` and pathspec elements, which are allowed after a double hyphen `--` for disambiguation. -+ -When pathspec is given to 'git stash push', the new stash entry records the -modified states only for the files that match the pathspec. The index -entries and working tree files are then rolled back to the state in -HEAD only for these files, too, leaving files that do not match the -pathspec intact. -+ -If the `--keep-index` option is used, all changes already added to the -index are left intact. -+ -If the `--include-untracked` option is used, all untracked files are also -stashed and then cleaned up with `git clean`, leaving the working directory -in a very clean state. If the `--all` option is used instead then the -ignored files are stashed and cleaned in addition to the untracked files. -+ -With `--patch`, you can interactively select hunks from the diff -between HEAD and the working tree to be stashed. The stash entry is -constructed such that its index state is the same as the index state -of your repository, and its worktree contains only the changes you -selected interactively. The selected changes are then rolled back -from your worktree. See the ``Interactive Mode'' section of -linkgit:git-add[1] to learn how to operate the `--patch` mode. -+ -The `--patch` option implies `--keep-index`. You can use -`--no-keep-index` to override this. save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]:: This option is deprecated in favour of 'git stash push'. It - differs from "stash push" in that it cannot take pathspecs. + differs from "stash push" in that it cannot take pathspec. Instead, all non-option arguments are concatenated to form the stash message. @@ -111,7 +87,7 @@ show [<options>] [<stash>]:: Show the changes recorded in the stash entry as a diff between the stashed contents and the commit back when the stash entry was first - created. When no `<stash>` is given, it shows the latest one. + created. By default, the command shows the diffstat, but it will accept any format known to 'git diff' (e.g., `git stash show -p stash@{1}` to view the second most recent entry in patch form). @@ -128,14 +104,6 @@ pop [--index] [-q|--quiet] [<stash>]:: Applying the state can fail with conflicts; in this case, it is not removed from the stash list. You need to resolve the conflicts by hand and call `git stash drop` manually afterwards. -+ -If the `--index` option is used, then tries to reinstate not only the working -tree's changes, but also the index's ones. However, this can fail, when you -have conflicts (which are stored in the index, where you therefore can no -longer apply the changes as they were originally). -+ -When no `<stash>` is given, `stash@{0}` is assumed, otherwise `<stash>` must -be a reference of the form `stash@{<revision>}`. apply [--index] [-q|--quiet] [<stash>]:: @@ -149,8 +117,7 @@ branch <branchname> [<stash>]:: the commit at which the `<stash>` was originally created, applies the changes recorded in `<stash>` to the new working tree and index. If that succeeds, and `<stash>` is a reference of the form - `stash@{<revision>}`, it then drops the `<stash>`. When no `<stash>` - is given, applies the latest one. + `stash@{<revision>}`, it then drops the `<stash>`. + This is useful if the branch on which you ran `git stash push` has changed enough that `git stash apply` fails due to conflicts. Since @@ -166,9 +133,6 @@ clear:: drop [-q|--quiet] [<stash>]:: Remove a single stash entry from the list of stash entries. - When no `<stash>` is given, it removes the latest one. - i.e. `stash@{0}`, otherwise `<stash>` must be a valid stash - log reference of the form `stash@{<revision>}`. create:: @@ -185,6 +149,98 @@ store:: reflog. This is intended to be useful for scripts. It is probably not the command you want to use; see "push" above. +OPTIONS +------- +-a:: +--all:: + This option is only valid for `push` and `save` commands. ++ +All ignored and untracked files are also stashed and then cleaned +up with `git clean`. + +-u:: +--include-untracked:: + This option is only valid for `push` and `save` commands. ++ +All untracked files are also stashed and then cleaned up with +`git clean`. + +--index:: + This option is only valid for `pop` and `apply` commands. ++ +Tries to reinstate not only the working tree's changes, but also +the index's ones. However, this can fail, when you have conflicts +(which are stored in the index, where you therefore can no longer +apply the changes as they were originally). + +-k:: +--keep-index:: +--no-keep-index:: + This option is only valid for `push` and `save` commands. ++ +All changes already added to the index are left intact. + +-p:: +--patch:: + This option is only valid for `push` and `save` commands. ++ +Interactively select hunks from the diff between HEAD and the +working tree to be stashed. The stash entry is constructed such +that its index state is the same as the index state of your +repository, and its worktree contains only the changes you selected +interactively. The selected changes are then rolled back from your +worktree. See the ``Interactive Mode'' section of linkgit:git-add[1] +to learn how to operate the `--patch` mode. ++ +The `--patch` option implies `--keep-index`. You can use +`--no-keep-index` to override this. + +--pathspec-from-file=<file>:: + This option is only valid for `push` command. ++ +Pathspec is passed in `<file>` instead of commandline args. If +`<file>` is exactly `-` then standard input is used. Pathspec +elements are separated by LF or CR/LF. Pathspec elements can be +quoted as explained for the configuration variable `core.quotePath` +(see linkgit:git-config[1]). See also `--pathspec-file-nul` and +global `--literal-pathspecs`. + +--pathspec-file-nul:: + This option is only valid for `push` command. ++ +Only meaningful with `--pathspec-from-file`. Pathspec elements are +separated with NUL character and all other characters are taken +literally (including newlines and quotes). + +-q:: +--quiet:: + This option is only valid for `apply`, `drop`, `pop`, `push`, + `save`, `store` commands. ++ +Quiet, suppress feedback messages. + +\--:: + This option is only valid for `push` command. ++ +Separates pathspec from options for disambiguation purposes. + +<pathspec>...:: + This option is only valid for `push` command. ++ +The new stash entry records the modified states only for the files +that match the pathspec. The index entries and working tree files +are then rolled back to the state in HEAD only for these files, +too, leaving files that do not match the pathspec intact. ++ +For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. + +<stash>:: + This option is only valid for `apply`, `branch`, `drop`, `pop`, + `show` commands. ++ +A reference of the form `stash@{<revision>}`. When no `<stash>` is +given, the latest stash is assumed (that is, `stash@{0}`). + DISCUSSION ---------- diff --git a/Documentation/git.txt b/Documentation/git.txt index b0672bd806..9d6769e95a 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -493,6 +493,12 @@ double-quotes and respecting backslash escapes. E.g., the value details. This variable has lower precedence than other path variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY... +`GIT_DEFAULT_HASH_ALGORITHM`:: + If this variable is set, the default hash algorithm for new + repositories will be set to this value. This value is currently + ignored when cloning; the setting of the remote repository + is used instead. The default is "sha1". + Git Commits ~~~~~~~~~~~ `GIT_AUTHOR_NAME`:: diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 373cfa2264..92e4ba6a2f 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -126,6 +126,11 @@ usage: git describe [<options>] <commit-ish>* --long always use long format --abbrev[=<n>] use <n> digits to display SHA-1s --------------------------------------------- ++ +Note that some subcommand (e.g. `git grep`) may behave differently +when there are things on the command line other than `-h`, but `git +subcmd -h` without anything else on the command line is meant to +consistently give the usage. --help-all:: Some Git commands take options that are only used for plumbing or that diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt index ca4378740c..73be8b49f8 100644 --- a/Documentation/howto/maintain-git.txt +++ b/Documentation/howto/maintain-git.txt @@ -154,15 +154,17 @@ by doing the following: - Anything unobvious that is applicable to 'master' (in other words, does not depend on anything that is still in 'next' and not in 'master') is applied to a new topic branch that - is forked from the tip of 'master'. This includes both + is forked from the tip of 'master' (or the last feature release, + which is a bit older than 'master'). This includes both enhancements and unobvious fixes to 'master'. A topic branch is named as ai/topic where "ai" is two-letter string named after author's initial and "topic" is a descriptive name of the topic (in other words, "what's the series is about"). - An unobvious fix meant for 'maint' is applied to a new - topic branch that is forked from the tip of 'maint'. The - topic is named as ai/maint-topic. + topic branch that is forked from the tip of 'maint' (or the + oldest and still relevant maintenance branch). The + topic may be named as ai/maint-topic. - Changes that pertain to an existing topic are applied to the branch, but: @@ -174,24 +176,40 @@ by doing the following: - Replacement patches to an existing topic are accepted only for commits not in 'next'. - The above except the "replacement" are all done with: + The initial round is done with: $ git checkout ai/topic ;# or "git checkout -b ai/topic master" $ git am -sc3 mailbox - while patch replacement is often done by: + and replacing an existing topic with subsequent round is done with: - $ git format-patch ai/topic~$n..ai/topic ;# export existing + $ git checkout master...ai/topic ;# try to reapply to the same base + $ git am -sc3 mailbox + + to prepare the new round on a detached HEAD, and then + + $ git range-diff @{-1}... + $ git diff @{-1} - then replace some parts with the new patch, and reapplying: + to double check what changed since the last round, and finally - $ git checkout ai/topic - $ git reset --hard ai/topic~$n - $ git am -sc3 -s 000*.txt + $ git checkout -B @{-1} + + to conclude (the last step is why a topic already in 'next' is + not replaced but updated incrementally). + + Whether it is the initial round or a subsequent round, the topic + may not build even in isolation, or may break the build when + merged to integration branches due to bugs. There may already + be obvious and trivial improvements suggested on the list. The + maintainer often adds an extra commit, with "SQUASH???" in its + title, to fix things up, before publishing the integration + branches to make it usable by other developers for testing. + These changes are what the maintainer is not 100% committed to + (trivial typofixes etc. are often squashed directly into the + patches that need fixing, without being applied as a separate + "SQUASH???" commit), so that they can be removed easily as needed. - The full test suite is always run for 'maint' and 'master' - after patch application; for topic branches the tests are run - as time permits. - Merge maint to master as needed: @@ -371,6 +389,14 @@ Some observations to be made. be included in the next feature release. Being in the 'master' branch typically is. + * Due to the nature of "SQUASH???" fix-ups, if the original author + agrees with the suggested changes, it is OK to squash them to + appropriate patches in the next round (when the suggested change + is small enough, the author should not even bother with + "Helped-by"). It is also OK to drop them from the next round + when the original author does not agree with the suggestion, but + the author is expected to say why somewhere in the discussion. + Appendix -------- |