Commit 6eeb9f0b authored by Duy Nguyen's avatar Duy Nguyen

Merge remote-tracking branch 'pclouds/switch-and-restore-forever' into HEAD

parents 258ab09e f17adc55
......@@ -142,6 +142,7 @@
/git-request-pull
/git-rerere
/git-reset
/git-restore
/git-rev-list
/git-rev-parse
/git-revert
......@@ -166,6 +167,7 @@
/git-submodule
/git-submodule--helper
/git-svn
/git-switch
/git-symbolic-ref
/git-tag
/git-unpack-file
......
......@@ -42,7 +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 @@ advice.*::
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
......
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 @@ branch.autoSetupMerge::
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.<name>.rebase").
When `never`, rebase is never automatically set to true.
......
checkout.defaultRemote::
When you run 'git checkout <something>' and only have one
When you run 'git checkout <something>'
or 'git switch <something>' and only have one
remote, it may implicitly fall back on checking out and
tracking e.g. 'origin/<something>'. This stops working as soon
as you have more than one remote with a '<something>'
......@@ -8,16 +9,10 @@ checkout.defaultRemote::
disambiguation. The typical use-case is to set this to
`origin`.
+
Currently this is used by linkgit:git-checkout[1] when 'git checkout
<something>' will checkout the '<something>' branch on another remote,
Currently this is used by linkgit:git-switch[1] and
linkgit:git-checkout[1] when 'git checkout <something>'
or 'git switch <something>'
will checkout the '<something>' branch on another remote,
and by linkgit:git-worktree[1] when 'git worktree add' refers to a
remote branch. This setting might be used for other checkout-like
commands or functionality in the future.
checkout.optimizeNewBranch::
Optimizes the performance of "git checkout -b <new_branch>" when
using sparse-checkout. When set to true, git will not update the
repo based on the current sparse-checkout settings. This means it
will not update the skip-worktree bit in the index nor add/remove
files in the working directory to reflect the current sparse checkout
settings nor will it show the local changes.
......@@ -78,7 +78,8 @@ diff.external::
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
......
......@@ -2,7 +2,8 @@ interactive.singleKey::
In interactive commands, allow the user to provide one-letter
input with a single key (i.e., without hitting enter).
Currently this is used by the `--patch` mode of
linkgit:git-add[1], linkgit:git-checkout[1], linkgit:git-commit[1],
linkgit:git-add[1], linkgit:git-checkout[1],
linkgit:git-restore[1], linkgit:git-commit[1],
linkgit:git-reset[1], and linkgit:git-stash[1]. Note that this
setting is silently ignored if portable keystroke input
is not available; requires the Perl module Term::ReadKey.
......
......@@ -48,7 +48,7 @@ The command's second form creates a new branch head named <branchname>
which points to the current `HEAD`, or <start-point> if given.
Note that this will create the new branch, but it will not switch the
working tree to it; use "git checkout <newbranch>" to switch to the
working tree to it; use "git switch <newbranch>" to switch to the
new branch.
When a local branch is started off a remote-tracking branch, Git sets up the
......@@ -198,7 +198,7 @@ This option is only applicable in non-verbose mode.
+
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.
......@@ -297,7 +297,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
......@@ -322,9 +322,9 @@ $ git branch -D test <2>
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:
......
......@@ -88,7 +88,8 @@ but it is explicitly forbidden at the beginning of a branch name).
When run with `--branch` option in a repository, the input is first
expanded for the ``previous checkout syntax''
`@{-n}`. For example, `@{-1}` is a way to refer the last thing that
was checked out using "git checkout" operation. This option should be
was checked out using "git switch" or "git checkout" operation.
This option should be
used by porcelains to accept this syntax anywhere a branch name is
expected, so they can act as if you typed the branch name. As an
exception note that, the ``previous checkout operation'' might result
......
This diff is collapsed.
......@@ -63,7 +63,7 @@ OPTIONS
still use the ignore rules given with `-e` options from the command
line. This allows removing all untracked
files, including build products. This can be used (possibly in
conjunction with 'git reset') to create a pristine
conjunction with 'git restore' or 'git reset') to create a pristine
working directory to test a clean build.
-X::
......
......@@ -359,7 +359,7 @@ When recording your own work, the contents of modified files in
your working tree are temporarily stored to a staging area
called the "index" with 'git add'. A file can be
reverted back, only in the index but not in the working tree,
to that of the last commit with `git reset HEAD -- <file>`,
to that of the last commit with `git restore --staged <file>`,
which effectively reverts 'git add' and prevents the changes to
this file from participating in the next commit. After building
the state to be committed incrementally with these commands,
......
......@@ -421,8 +421,8 @@ One way to test if your MUA is set up correctly is:
* Apply it:
$ git fetch <project> master:test-apply
$ git checkout test-apply
$ git reset --hard
$ git switch test-apply
$ git restore --source=HEAD --staged --worktree :/
$ git am a.patch
If it does not apply correctly, there can be various reasons.
......
......@@ -149,7 +149,7 @@ instead.
Discussion on fork-point mode
-----------------------------
After working on the `topic` branch created with `git checkout -b
After working on the `topic` branch created with `git switch -c
topic origin/master`, the history of remote-tracking branch
`origin/master` may have been rewound and rebuilt, leading to a
history of this shape:
......
......@@ -88,6 +88,11 @@ will be appended to the specified message.
Allow the rerere mechanism to update the index with the
result of auto-conflict resolution if possible.
--overwrite-ignore::
--no-overwrite-ignore::
Silently overwrite ignored files from the merge result. This
is the default behavior. Use `--no-overwrite-ignore` to abort.
--abort::
Abort the current conflict resolution process, and
try to reconstruct the pre-merge state.
......
......@@ -17,7 +17,7 @@ SYNOPSIS
DESCRIPTION
-----------
If <branch> is specified, 'git rebase' will perform an automatic
`git checkout <branch>` before doing anything else. Otherwise
`git switch <branch>` before doing anything else. Otherwise
it remains on the current branch.
If <upstream> is not specified, the upstream configured in
......
......@@ -230,7 +230,7 @@ $ git branch -r
staging/master
staging/staging-linus
staging/staging-next
$ git checkout -b staging staging/master
$ git switch -c staging staging/master
...
------------
......
......@@ -91,7 +91,7 @@ For such a test, you need to merge master and topic somehow.
One way to do it is to pull master into the topic branch:
------------
$ git checkout topic
$ git switch topic
$ git merge master
o---*---o---+ topic
......@@ -113,10 +113,10 @@ the upstream might have been advanced since the test merge `+`,
in which case the final commit graph would look like this:
------------
$ git checkout topic
$ git switch topic
$ git merge master
$ ... work on both topic and master branches
$ git checkout master
$ git switch master
$ git merge topic
o---*---o---+---o---o topic
......@@ -136,11 +136,11 @@ merges, you could blow away the test merge, and keep building on
top of the tip before the test merge:
------------
$ git checkout topic
$ git switch topic
$ git merge master
$ git reset --hard HEAD^ ;# rewind the test merge
$ ... work on both topic and master branches
$ git checkout master
$ git switch master
$ git merge topic
o---*---o-------o---o topic
......
......@@ -25,12 +25,13 @@ The `<tree-ish>`/`<commit>` defaults to `HEAD` in all forms.
the current branch.)
+
This means that `git reset <paths>` is the opposite of `git add
<paths>`.
<paths>`. This command is equivalent to
`git restore [--source=<tree-ish>] --staged <paths>...`.
+
After running `git reset <paths>` to update the index entry, you can
use linkgit:git-checkout[1] to check the contents out of the index to
the working tree.
Alternatively, using linkgit:git-checkout[1] and specifying a commit, you
use linkgit:git-restore[1] to check the contents out of the index to
the working tree. Alternatively, using linkgit:git-restore[1]
and specifying a commit with `--source`, you
can copy the contents of a path out of a commit to the index and to the
working tree in one go.
......@@ -86,8 +87,8 @@ but carries forward unmerged index entries.
changes, reset is aborted.
--
If you want to undo a commit other than the latest on a branch,
linkgit:git-revert[1] is your friend.
See "Reset, restore and revert" in linkgit:git[1] for the differences
between the three commands.
OPTIONS
......@@ -149,9 +150,9 @@ See also the `--amend` option to linkgit:git-commit[1].
Undo a commit, making it a topic branch::
+
------------
$ git branch topic/wip <1>
$ git reset --hard HEAD~3 <2>
$ git checkout topic/wip <3>
$ git branch topic/wip <1>
$ git reset --hard HEAD~3 <2>
$ git switch topic/wip <3>
------------
+
<1> You have made some commits, but realize they were premature
......@@ -232,13 +233,13 @@ working tree are not in any shape to be committed yet, but you
need to get to the other branch for a quick bugfix.
+
------------
$ git checkout feature ;# you were working in "feature" branch and
$ work work work ;# got interrupted
$ git switch feature ;# you were working in "feature" branch and
$ work work work ;# got interrupted
$ git commit -a -m "snapshot WIP" <1>
$ git checkout master
$ git switch master
$ fix fix fix
$ git commit ;# commit with real log
$ git checkout feature
$ git switch feature
$ git reset --soft HEAD^ ;# go back to WIP state <2>
$ git reset <3>
------------
......@@ -279,18 +280,18 @@ reset it while keeping the changes in your working tree.
+
------------
$ git tag start
$ git checkout -b branch1
$ git switch -c branch1
$ edit
$ git commit ... <1>
$ edit
$ git checkout -b branch2 <2>
$ git switch -c branch2 <2>
$ git reset --keep start <3>
------------
+
<1> This commits your first edits in `branch1`.
<2> In the ideal world, you could have realized that the earlier
commit did not belong to the new topic when you created and switched
to `branch2` (i.e. `git checkout -b branch2 start`), but nobody is
to `branch2` (i.e. `git switch -c branch2 start`), but nobody is
perfect.
<3> But you can use `reset --keep` to remove the unwanted commit after
you switched to `branch2`.
......
git-restore(1)
==============
NAME
----
git-restore - Restore working tree files
SYNOPSIS
--------
[verse]
'git restore' [<options>] [--source=<tree>] [--staged] [--worktree] <pathspec>...
'git restore' (-p|--patch) [<options>] [--source=<tree>] [--staged] [--worktree] [<pathspec>...]
DESCRIPTION
-----------
Restore specified paths in the working tree with some contents from a
restore source. If a path is tracked but does not exist in the restore
source, it will be removed to match the source.
The command can also be used to restore the content in the index with
`--staged`, or restore both the working tree and the index with
`--staged --worktree`.
By default, the restore sources for working tree and the index are the
index and `HEAD` respectively. `--source` could be used to specify a
commit as the restore source.
See "Reset, restore and revert" in linkgit:git[1] for the differences
between the three commands.
THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
OPTIONS
-------
-s <tree>::
--source=<tree>::
Restore the working tree files with the content from the given
tree. It is common to specify the source tree by naming a
commit, branch or tag associated with it.
+
If not specified, the default restore source for the working tree is
the index, and the default restore source for the index index is
`HEAD`. When both `--staged` and `--worktree` are specified,
`--source` must also be specified.
-p::
--patch::
Interactively select hunks in the difference between the
restore source and the restore location. See the ``Interactive
Mode'' section of linkgit:git-add[1] to learn how to operate
the `--patch` mode.
+
Note that `--patch` can accept no pathspec and will prompt to restore
all modified paths.
-W::
--worktree::
-S::
--staged::
Specify the restore location. If neither option is specified,
by default the working tree is restored. Specifying `--staged`
will only restore the index. Specifying both restores both.
-q::
--quiet::
Quiet, suppress feedback messages. Implies `--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
attached to a terminal, regardless of `--quiet`.
--ours::
--theirs::
When restoring files in the working tree from the index, use
stage #2 ('ours') or #3 ('theirs') for unmerged paths.
+
Note that during `git rebase` and `git pull --rebase`, 'ours' and
'theirs' may appear swapped. See the explanation of the same options
in linkgit:git-checkout[1] for details.
-m::
--merge::
When restoring files on the working tree from the index,
recreate the conflicted merge in the unmerged paths.
--conflict=<style>::
The same as `--merge` option above, but changes the way the
conflicting hunks are presented, overriding the
`merge.conflictStyle` configuration variable. Possible values
are "merge" (default) and "diff3" (in addition to what is
shown by "merge" style, shows the original contents).
--ignore-unmerged::
When restoring files on the working tree from the index, do
not abort the operation if there are unmerged entries and
neither `--ours`, `--theirs`, `--merge` or `--conflict` is
specified. Unmerged paths on the working tree are left alone.
--ignore-skip-worktree-bits::
In sparse checkout mode, by default is to only update entries
matched by `<pathspec>` and sparse patterns in
$GIT_DIR/info/sparse-checkout. This option ignores the sparse
patterns and unconditionally restores any files in
`<pathspec>`.
--overlay::
--no-overlay::
In overlay mode, the command never removes files when
restoring. In no-overlay mode, tracked files that do not
appear in the `--source` tree are removed, to make them match
`<tree>` exactly. The default is no-overlay mode.
EXAMPLES
--------
The following sequence switches to the `master` branch, reverts the
`Makefile` to two revisions back, deletes hello.c by mistake, and gets
it back from the index.
------------
$ git switch master
$ git restore --source master~2 Makefile <1>
$ rm -f hello.c
$ git restore hello.c <2>
------------
<1> take a file out of another commit
<2> restore hello.c from the index
If you want to restore _all_ C source files to match the version in
the index, you can say
------------
$ git restore '*.c'
------------
Note the quotes around `*.c`. The file `hello.c` will also be
restored, even though it is no longer in the working tree, because the
file globbing is used to match entries in the index (not in the
working tree by the shell).
To restore all files in the current directory
------------
$ git restore .
------------
or to restore all working tree files with 'top' pathspec magic (see
linkgit:gitglossary[7])
------------
$ git restore :/
------------
To restore a file in the index to match the version in `HEAD` (this is
the same as using linkgit:git-reset[1])
------------
$ git restore --staged hello.c
------------
or you can restore both the index and the working tree (this the same
as using linkgit:git-checkout[1])
------------
$ git restore --source=HEAD --staged --worktree hello.c
------------
or the short form which is more practical but less readable:
------------
$ git restore -s@ -SW hello.c
------------
SEE ALSO
--------
linkgit:git-checkout[1],
linkgit:git-reset[1]
GIT
---
Part of the linkgit:git[1] suite
......@@ -26,10 +26,13 @@ effect of some earlier commits (often only a faulty one). If you want to
throw away all uncommitted changes in your working directory, you
should see linkgit:git-reset[1], particularly the `--hard` option. If
you want to extract specific files as they were in another commit, you
should see linkgit:git-checkout[1], specifically the `git checkout
<commit> -- <filename>` syntax. Take care with these alternatives as
should see linkgit:git-restore[1], specifically the `--source`
option. Take care with these alternatives as
both will discard uncommitted changes in your working directory.
See "Reset, restore and revert" in linkgit:git[1] for the differences
between the three commands.
OPTIONS
-------
<commit>...::
......
......@@ -8,7 +8,7 @@ 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] [--staged] [--ignore-unmatch] [--quiet] [--] <file>...
DESCRIPTION
-----------
......@@ -55,10 +55,11 @@ OPTIONS
the list of files, (useful when filenames might be mistaken
for command-line options).
--staged::
--cached::
Use this option to unstage and remove paths only from the index.
Working tree files, whether modified or not, will be
left alone.
Working tree files, whether modified or not, will be left
alone. `--cached` is synonym for `--staged`.
--ignore-unmatch::
Exit with a zero status even if no files matched.
......
......@@ -235,12 +235,12 @@ return to your original branch to make the emergency fix, like this:
+
----------------------------------------------------------------
# ... hack hack hack ...
$ git checkout -b my_wip
$ git switch -c my_wip
$ git commit -a -m "WIP"
$ git checkout master
$ git switch master
$ edit emergency fix
$ git commit -a -m "Fix in a hurry"
$ git checkout my_wip
$ git switch my_wip
$ git reset --soft HEAD^
# ... continue hacking ...
----------------------------------------------------------------
......@@ -293,7 +293,8 @@ SEE ALSO
linkgit:git-checkout[1],
linkgit:git-commit[1],
linkgit:git-reflog[1],
linkgit:git-reset[1]
linkgit:git-reset[1],
linkgit:git-switch[1]
GIT
---
......
git-switch(1)
=============
NAME
----
git-switch - Switch branches
SYNOPSIS
--------
[verse]
'git switch' [<options>] [--no-guess] <branch>
'git switch' [<options>] --detach [<start-point>]
'git switch' [<options>] (-c|-C) <new-branch> [<start-point>]
'git switch' [<options>] --orphan <new-branch>
DESCRIPTION
-----------
Switch to a specified branch. The working tree and the index are
updated to match the branch. All new commits will be added to the tip
of this branch.
Optionally a new branch could be created with either `-c`, `-C`,
automatically from a remote branch of same name (see `--guess`), or
detach the working tree from any branch with `--detach`, along with
switching.
Switching branches does not require a clean index and working tree
(i.e. no differences compared to `HEAD`). The operation is aborted
however if the operation leads to loss of local changes, unless told
otherwise with `--discard-changes` or `--merge`.
THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
OPTIONS
-------
<branch>::
Branch to switch to.
<new-branch>::
Name for the new branch.
<start-point>::
The starting point for the new branch. Specifying a
`<start-point>` allows you to create a branch based on some
other point in history than where HEAD currently points. (Or,
in the case of `--detach`, allows you to inspect and detach
from some other point.)
+
You can use the `@{-N}` syntax to refer to the N-th last
branch/commit switched to using "git switch" or "git checkout"
operation. You may also specify `-` which is synonymous to `@{-1}`.
This is often used to switch quickly between two branches, or to undo
a branch switch by mistake.
+
As a special case, 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`.
-c <new-branch>::
--create <new-branch>::
Create a new branch named `<new-branch>` starting at
`<start-point>` before switching to the branch. This is a
convenient shortcut for:
+
------------
$ git branch <new-branch>
$ git switch <new-branch>
------------
-C <new-branch>::
--force-create <new-branch>::
Similar to `--create` except that if `<new-branch>` already
exists, it will be reset to `<start-point>`. This is a
convenient shortcut for:
+
------------
$ git branch -f <new-branch>
$ git switch <new-branch>
------------
-d::
--detach::
Switch to a commit for inspection and discardable
experiments. See the "DETACHED HEAD" section in
linkgit:git-checkout[1] for details.
+
`--detach` is implied when the working tree is already in detached
head mode and the switch target is not a branch.
--guess::
--no-guess::
If `<branch>` is not found but there does exist a tracking
branch in exactly one remote (call it `<remote>`) with a
matching name, treat as equivalent to
+
------------
$ git switch -c <branch> --track <remote>/<branch>
------------
+
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 `<branch>` isn't
unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin`
to always checkout remote branches from there if `<branch>` is
ambiguous but exists on the 'origin' remote. See also
`checkout.defaultRemote` in linkgit:git-config[1].
+
`--guess` is the default behavior. Use `--no-guess` to disable it.
-f::
--force::
An alias for `--discard-changes`.
--discard-changes::
Proceed even if the index or the working tree differs from
`HEAD`. Both the index and working tree are restored to match
the switching target. If `--recurse-submodules` is specified,
submodule content is also restored to match the switching
target. This is used to throw away local changes.
-m::
--merge::
If you have local modifications to one or more files that are
different between the current branch and the branch to which
you are switching, the command refuses to switch branches in
order to preserve your modifications in context. However,
with this option, a three-way merge between the current
branch, your working tree contents, and the new branch is
done, and you will be on the new branch.
+
When a merge conflict happens, the index entries for conflicting
paths are left unmerged, and you need to resolve the conflicts
and mark the resolved paths with `git add` (or `git rm` if the merge
should result in deletion of the path).
--conflict=<style>::
The same as `--merge` option above, but changes the way the
conflicting hunks are presented, overriding the
`merge.conflictStyle` configuration variable. Possible values are
"merge" (default) and "diff3" (in addition to what is shown by
"merge" style, shows the original contents).
-q::
--quiet::
Quiet, suppress feedback messages.