From: Junio C Hamano Date: Tue, 9 Jul 2019 22:25:44 +0000 (-0700) Subject: Merge branch 'nd/switch-and-restore' X-Git-Tag: v2.23.0-rc0~64 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/f496b064fc1135e0dded7f93d85d72eb0b302c22?hp=-c Merge branch 'nd/switch-and-restore' Two new commands "git switch" and "git restore" are introduced to split "checking out a branch to work on advancing its history" and "checking out paths out of the index and/or a tree-ish to work on advancing the current history" out of the single "git checkout" command. * nd/switch-and-restore: (46 commits) completion: disable dwim on "git switch -d" switch: allow to switch in the middle of bisect t2027: use test_must_be_empty Declare both git-switch and git-restore experimental help: move git-diff and git-reset to different groups doc: promote "git restore" user-manual.txt: prefer 'merge --abort' over 'reset --hard' completion: support restore t: add tests for restore restore: support --patch restore: replace --force with --ignore-unmerged restore: default to --source=HEAD when only --staged is specified restore: reject invalid combinations with --staged restore: add --worktree and --staged checkout: factor out worktree checkout code restore: disable overlay mode by default restore: make pathspec mandatory restore: take tree-ish from --source option instead checkout: split part of it to new command 'restore' doc: promote "git switch" ... --- f496b064fc1135e0dded7f93d85d72eb0b302c22 diff --combined .gitignore index 4470d7cfc0,fb377106be..40326140c7 --- a/.gitignore +++ b/.gitignore @@@ -82,7 -82,7 +82,7 @@@ /git-init-db /git-interpret-trailers /git-instaweb -/git-legacy-rebase +/git-legacy-stash /git-log /git-ls-files /git-ls-remote @@@ -122,6 -122,9 +122,6 @@@ /git-range-diff /git-read-tree /git-rebase -/git-rebase--am -/git-rebase--common -/git-rebase--interactive /git-rebase--preserve-merges /git-receive-pack /git-reflog @@@ -132,6 -135,7 +132,6 @@@ /git-remote-ftps /git-remote-fd /git-remote-ext -/git-remote-testgit /git-remote-testpy /git-remote-testsvn /git-repack @@@ -139,6 -143,7 +139,7 @@@ /git-request-pull /git-rerere /git-reset + /git-restore /git-rev-list /git-rev-parse /git-revert @@@ -163,6 -168,7 +164,7 @@@ /git-submodule /git-submodule--helper /git-svn + /git-switch /git-symbolic-ref /git-tag /git-unpack-file diff --combined Documentation/config/advice.txt index ec4f6ae658,239d479506..d5fd05ce81 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@@ -42,7 -42,8 +42,8 @@@ advice.*: state in the output of linkgit:git-status[1], in the template shown when writing commit messages in linkgit:git-commit[1], and in the help message shown - by linkgit:git-checkout[1] when switching branch. + by linkgit:git-switch[1] or + linkgit:git-checkout[1] when switching branch. statusUoption:: Advise to consider using the `-u` option to linkgit:git-status[1] when the command takes more than 2 seconds to enumerate untracked @@@ -62,12 -63,14 +63,14 @@@ your information is guessed from the system username and domain name. detachedHead:: - Advice shown when you used linkgit:git-checkout[1] to - move to the detach HEAD state, to instruct how to create - a local branch after the fact. + Advice shown when you used + linkgit:git-switch[1] or linkgit:git-checkout[1] + to move to the detach HEAD state, to instruct how to + create a local branch after the fact. checkoutAmbiguousRemoteBranchName:: Advice shown when the argument to - linkgit:git-checkout[1] ambiguously resolves to a + linkgit:git-checkout[1] and linkgit:git-switch[1] + ambiguously resolves to a remote tracking branch on more than one remote in situations where an unambiguous argument would have otherwise caused a remote-tracking branch to be @@@ -90,6 -93,4 +93,6 @@@ waitingForEditor:: Print a message to the terminal whenever Git is waiting for editor input from the user. + nestedTag:: + Advice shown if a user attempts to recursively tag a tag object. -- diff --combined Documentation/config/branch.txt index 8f4b3faadd,8050466159..a592d522a7 --- a/Documentation/config/branch.txt +++ b/Documentation/config/branch.txt @@@ -1,5 -1,5 +1,5 @@@ branch.autoSetupMerge:: - Tells 'git branch' and 'git checkout' to set up new branches + Tells 'git branch', 'git switch' and 'git checkout' to set up new branches so that linkgit:git-pull[1] will appropriately merge from the starting point branch. Note that even if this option is not set, this behavior can be chosen per-branch using the `--track` @@@ -11,7 -11,7 +11,7 @@@ branch. This option defaults to true. branch.autoSetupRebase:: - When a new branch is created with 'git branch' or 'git checkout' + When a new branch is created with 'git branch', 'git switch' or 'git checkout' that tracks another branch, this variable tells Git to set up pull to rebase instead of merge (see "branch..rebase"). When `never`, rebase is never automatically set to true. @@@ -85,9 -85,9 +85,9 @@@ When `merges`, pass the `--rebase-merge so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When preserve, also pass `--preserve-merges` along to 'git rebase' -so that locally committed merge commits will not be flattened -by running 'git pull'. +When `preserve` (deprecated in favor of `merges`), also pass +`--preserve-merges` along to 'git rebase' so that locally committed merge +commits will not be flattened by running 'git pull'. + When the value is `interactive`, the rebase is run in interactive mode. + diff --combined Documentation/config/diff.txt index 2c4c9ba27a,b3b304ee12..5afb5a2cbc --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@@ -10,7 -10,7 +10,7 @@@ diff.autoRefreshIndex: diff.dirstat:: A comma separated list of `--dirstat` parameters specifying the - default behavior of the `--dirstat` option to linkgit:git-diff[1]` + default behavior of the `--dirstat` option to linkgit:git-diff[1] and friends. The defaults can be overridden on the command line (using `--dirstat=`). The fallback defaults (when not changed by `diff.dirstat`) are `changes,noncumulative,3`. @@@ -73,12 -73,13 +73,13 @@@ diff.external: environment variable. The command is called with parameters as described under "git Diffs" in linkgit:git[1]. Note: if you want to use an external diff program only on a subset of - your files, you might want to use linkgit:gitattributes[5] instead. + your files, you might want to use linkgit:gitattributes[5] instead. diff.ignoreSubmodules:: Sets the default value of --ignore-submodules. Note that this affects only 'git diff' Porcelain, and not lower level 'diff' - commands such as 'git diff-files'. 'git checkout' also honors + commands such as 'git diff-files'. 'git checkout' + and 'git switch' also honor this setting when reporting uncommitted changes. Setting it to 'all' disables the submodule summary normally shown by 'git commit' and 'git status' when `status.submoduleSummary` is set unless it is diff --combined Documentation/git-branch.txt index 16e14c6282,1e2d89b174..135206ff4a --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@@ -8,14 -8,12 +8,14 @@@ git-branch - List, create, or delete br SYNOPSIS -------- [verse] -'git branch' [--color[=] | --no-color] [-r | -a] - [--list] [--show-current] [-v [--abbrev= | --no-abbrev]] +'git branch' [--color[=] | --no-color] [--show-current] + [-v [--abbrev= | --no-abbrev]] [--column[=] | --no-column] [--sort=] [(--merged | --no-merged) []] [--contains []] - [--points-at ] [--format=] [...] + [--points-at ] [--format=] + [(-r | --remotes) | (-a | --all)] + [--list] [...] 'git branch' [--track | --no-track] [-f] [] 'git branch' (--set-upstream-to= | -u ) [] 'git branch' --unset-upstream [] @@@ -28,19 -26,13 +28,19 @@@ DESCRIPTIO ----------- If `--list` is given, or if there are no non-option arguments, existing -branches are listed; the current branch will be highlighted with an -asterisk. Option `-r` causes the remote-tracking branches to be listed, -and option `-a` shows both local and remote branches. If a `` +branches are listed; the current branch will be highlighted in green and +marked with an asterisk. Any branches checked out in linked worktrees will +be highlighted in cyan and marked with a plus sign. Option `-r` causes the +remote-tracking branches to be listed, +and option `-a` shows both local and remote branches. + +If a `` is given, it is used as a shell wildcard to restrict the output to matching branches. If multiple patterns are given, a branch is shown if -it matches any of the patterns. Note that when providing a -``, you must use `--list`; otherwise the command is interpreted +it matches any of the patterns. + +Note that when providing a +``, you must use `--list`; otherwise the command may be interpreted as branch creation. With `--contains`, shows only the branches that contain the named commit @@@ -53,14 -45,10 +53,14 @@@ argument is missing it defaults to `HEA branch). The command's second form creates a new branch head named -which points to the current `HEAD`, or if given. +which points to the current `HEAD`, or if given. As a +special case, for , you may use `"A...B"` as a shortcut for +the merge base of `A` and `B` if there is exactly one merge base. You +can leave out at most one of `A` and `B`, in which case it defaults to +`HEAD`. Note that this will create the new branch, but it will not switch the - working tree to it; use "git checkout " to switch to the + working tree to it; use "git switch " to switch to the new branch. When a local branch is started off a remote-tracking branch, Git sets up the @@@ -161,12 -149,10 +161,12 @@@ This option is only applicable in non-v -r:: --remotes:: List or delete (if used with -d) the remote-tracking branches. + Combine with `--list` to match the optional pattern(s). -a:: --all:: List both remote-tracking branches and local branches. + Combine with `--list` to match optional pattern(s). -l:: --list:: @@@ -184,10 -170,8 +184,10 @@@ When in list mode, show sha1 and commit subject line for each head, along with relationship to upstream branch (if any). If given twice, print - the name of the upstream branch, as well (see also `git remote - show `). + the path of the linked worktree (if any) and the name of the upstream + branch, as well (see also `git remote show `). Note that the + current worktree's HEAD will not have its path printed (it will always + be your current directory). -q:: --quiet:: @@@ -214,7 -198,7 +214,7 @@@ + This behavior is the default when the start point is a remote-tracking branch. Set the branch.autoSetupMerge configuration variable to `false` if you - want `git checkout` and `git branch` to always behave as if `--no-track` + want `git switch`, `git checkout` and `git branch` to always behave as if `--no-track` were given. Set it to `always` if you want this behavior when the start-point is either a local or remote-tracking branch. @@@ -313,7 -297,7 +313,7 @@@ Start development from a known tag: $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 $ cd my2.6 $ git branch my2.6.14 v2.6.14 <1> - $ git checkout my2.6.14 + $ git switch my2.6.14 ------------ + <1> This step and the next one could be combined into a single step with @@@ -334,25 -318,13 +334,25 @@@ $ git branch -D tes <2> Delete the "test" branch even if the "master" branch (or whichever branch is currently checked out) does not have all commits from the test branch. +Listing branches from a specific remote:: ++ +------------ +$ git branch -r -l '/' <1> +$ git for-each-ref 'refs/remotes//' <2> +------------ ++ +<1> Using `-a` would conflate with any local branches you happen to + have been prefixed with the same pattern. +<2> `for-each-ref` can take a wide range of options. See linkgit:git-for-each-ref[1] + +Patterns will normally need quoting. NOTES ----- - If you are creating a branch that you want to checkout immediately, it is - easier to use the git checkout command with its `-b` option to create - a branch and check it out with a single command. + If you are creating a branch that you want to switch to immediately, + it is easier to use the "git switch" command with its `-c` option to + do the same thing with a single command. The options `--contains`, `--no-contains`, `--merged` and `--no-merged` serve four related but different purposes: diff --combined Documentation/git-checkout.txt index 964f912d29,a294652dd6..cf3cac0a2b --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@@ -23,31 -23,22 +23,22 @@@ or the specified tree. If no paths ar also update `HEAD` to set the specified branch as the current branch. - 'git checkout' :: - To prepare for working on , switch to it by updating + 'git checkout' []:: + To prepare for working on ``, switch to it by updating the index and the files in the working tree, and by pointing - HEAD at the branch. Local modifications to the files in the + `HEAD` at the branch. Local modifications to the files in the working tree are kept, so that they can be committed to the - . + ``. + - If is not found but there does exist a tracking branch in - exactly one remote (call it ) with a matching name, treat as - equivalent to + If `` is not found but there does exist a tracking branch in + exactly one remote (call it ``) with a matching name and + `--no-guess` is not specified, treat as equivalent to + ------------ $ git checkout -b --track / ------------ + - If the branch exists in multiple remotes and one of them is named by - the `checkout.defaultRemote` configuration variable, we'll use that - one for the purposes of disambiguation, even if the `` isn't - unique across all remotes. Set it to - e.g. `checkout.defaultRemote=origin` to always checkout remote - branches from there if `` is ambiguous but exists on the - 'origin' remote. See also `checkout.defaultRemote` in - linkgit:git-config[1]. - + - You could omit , in which case the command degenerates to + You could omit ``, in which case the command degenerates to "check out the current branch", which is a glorified no-op with rather expensive side-effects to show only the tracking information, if exists, for the current branch. @@@ -61,7 -52,7 +52,7 @@@ `--track` without `-b` implies branch creation; see the description of `--track` below. + - If `-B` is given, is created if it doesn't exist; otherwise, it + If `-B` is given, `` is created if it doesn't exist; otherwise, it is reset. This is the transactional equivalent of + ------------ @@@ -75,25 -66,25 +66,25 @@@ successful 'git checkout' --detach []:: 'git checkout' [--detach] :: - Prepare to work on top of , by detaching HEAD at it + Prepare to work on top of ``, by detaching `HEAD` at it (see "DETACHED HEAD" section), and updating the index and the files in the working tree. Local modifications to the files in the working tree are kept, so that the resulting working tree will be the state recorded in the commit plus the local modifications. + - When the argument is a branch name, the `--detach` option can - be used to detach HEAD at the tip of the branch (`git checkout - ` would check out that branch without detaching HEAD). + When the `` argument is a branch name, the `--detach` option can + be used to detach `HEAD` at the tip of the branch (`git checkout + ` would check out that branch without detaching `HEAD`). + - Omitting detaches HEAD at the tip of the current branch. + Omitting `` detaches `HEAD` at the tip of the current branch. 'git checkout' [] [--] ...:: Overwrite paths in the working tree by replacing with the - contents in the index or in the (most often a - commit). When a is given, the paths that - match the are updated both in the index and in + contents in the index or in the `` (most often a + commit). When a `` is given, the paths that + match the `` are updated both in the index and in the working tree. + The index may contain unmerged entries because of a previous failed merge. @@@ -118,7 -109,8 +109,8 @@@ OPTION --quiet:: Quiet, suppress feedback messages. - --[no-]progress:: + --progress:: + --no-progress:: Progress status is reported on the standard error stream by default when it is attached to a terminal, unless `--quiet` is specified. This flag enables progress reporting even if not @@@ -127,7 -119,7 +119,7 @@@ -f:: --force:: When switching branches, proceed even if the index or the - working tree differs from HEAD. This is used to throw away + working tree differs from `HEAD`. This is used to throw away local changes. + When checking out paths from the index, do not fail upon unmerged @@@ -154,12 -146,12 +146,12 @@@ on your side branch as `theirs` (i.e. " of it"). -b :: - Create a new branch named and start it at - ; see linkgit:git-branch[1] for details. + Create a new branch named `` and start it at + ``; see linkgit:git-branch[1] for details. -B :: - Creates the branch and start it at ; - if it already exists, then reset it to . This is + Creates the branch `` and start it at ``; + if it already exists, then reset it to ``. This is equivalent to running "git branch" with "-f"; see linkgit:git-branch[1] for details. @@@ -172,15 -164,36 +164,36 @@@ If no `-b` option is given, the name o derived from the remote-tracking branch, by looking at the local part of the refspec configured for the corresponding remote, and then stripping the initial part up to the "*". - This would tell us to use "hack" as the local branch when branching - off of "origin/hack" (or "remotes/origin/hack", or even - "refs/remotes/origin/hack"). If the given name has no slash, or the above + This would tell us to use `hack` as the local branch when branching + off of `origin/hack` (or `remotes/origin/hack`, or even + `refs/remotes/origin/hack`). If the given name has no slash, or the above guessing results in an empty name, the guessing is aborted. You can explicitly give a name with `-b` in such a case. --no-track:: Do not set up "upstream" configuration, even if the - branch.autoSetupMerge configuration variable is true. + `branch.autoSetupMerge` configuration variable is true. + + --guess:: + --no-guess:: + If `` is not found but there does exist a tracking + branch in exactly one remote (call it ``) with a + matching name, treat as equivalent to + + + ------------ + $ git checkout -b --track / + ------------ + + + If the branch exists in multiple remotes and one of them is named by + the `checkout.defaultRemote` configuration variable, we'll use that + one for the purposes of disambiguation, even if the `` isn't + unique across all remotes. Set it to + e.g. `checkout.defaultRemote=origin` to always checkout remote + branches from there if `` is ambiguous but exists on the + 'origin' remote. See also `checkout.defaultRemote` in + linkgit:git-config[1]. + + + Use `--no-guess` to disable this. -l:: Create the new branch's reflog; see linkgit:git-branch[1] for @@@ -189,21 -202,21 +202,21 @@@ --detach:: Rather than checking out a branch to work on it, check out a commit for inspection and discardable experiments. - This is the default behavior of "git checkout " when - is not a branch name. See the "DETACHED HEAD" section + This is the default behavior of `git checkout ` when + `` is not a branch name. See the "DETACHED HEAD" section below for details. --orphan :: - Create a new 'orphan' branch, named , started from - and switch to it. The first commit made on this + Create a new 'orphan' branch, named ``, started from + `` and switch to it. The first commit made on this new branch will have no parents and it will be the root of a new history totally disconnected from all the other branches and commits. + The index and the working tree are adjusted as if you had previously run - "git checkout ". This allows you to start a new history - that records a set of paths similar to by easily running - "git commit -a" to make the root commit. + `git checkout `. This allows you to start a new history + that records a set of paths similar to `` by easily running + `git commit -a` to make the root commit. + This can be useful when you want to publish the tree from a commit without exposing its full history. You might want to do this to publish @@@ -212,17 -225,17 +225,17 @@@ whose full history contains proprietar code. + If you want to start a disconnected history that records a set of paths - that is totally different from the one of , then you should + that is totally different from the one of ``, then you should clear the index and the working tree right after creating the orphan - branch by running "git rm -rf ." from the top level of the working tree. + branch by running `git rm -rf .` from the top level of the working tree. Afterwards you will be ready to prepare your new files, repopulating the working tree, by copying them from elsewhere, extracting a tarball, etc. --ignore-skip-worktree-bits:: In sparse checkout mode, `git checkout -- ` would - update only entries matched by and sparse patterns - in $GIT_DIR/info/sparse-checkout. This option ignores - the sparse patterns and adds back any files in . + update only entries matched by `` and sparse patterns + in `$GIT_DIR/info/sparse-checkout`. This option ignores + the sparse patterns and adds back any files in ``. -m:: --merge:: @@@ -242,29 -255,27 +255,29 @@@ should result in deletion of the path) + When checking out paths from the index, this option lets you recreate the conflicted merge in the specified paths. ++ +When switching branches with `--merge`, staged changes may be lost. --conflict=