[v2,7/7] Suggest other commands instead of "git checkout"
diff mbox series

Message ID 20181127165211.24763-8-pclouds@gmail.com
State New, archived
Headers show
Series
  • Introduce new commands switch-branch and checkout-files
Related show

Commit Message

Duy Nguyen Nov. 27, 2018, 4:52 p.m. UTC
The assumption made is here

- "git checkout" is a horrible monster that should only be touched
  with a two-meter pole

- there are other commands that can achieve the same thing

Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
 Documentation/git-branch.txt           |  8 ++--
 Documentation/git-check-ref-format.txt |  2 +-
 Documentation/git-format-patch.txt     |  2 +-
 Documentation/git-merge-base.txt       |  2 +-
 Documentation/git-rebase.txt           |  2 +-
 Documentation/git-remote.txt           |  2 +-
 Documentation/git-rerere.txt           | 10 ++---
 Documentation/git-reset.txt            | 18 ++++-----
 Documentation/git-revert.txt           |  2 +-
 Documentation/git-stash.txt            |  6 +--
 Documentation/gitattributes.txt        |  2 +-
 Documentation/gitcli.txt               |  4 +-
 Documentation/gitcore-tutorial.txt     | 18 ++++-----
 Documentation/giteveryday.txt          | 24 ++++++------
 Documentation/githooks.txt             |  5 ++-
 Documentation/gittutorial-2.txt        |  2 +-
 Documentation/gittutorial.txt          |  4 +-
 Documentation/revisions.txt            |  2 +-
 Documentation/user-manual.txt          | 54 +++++++++++++-------------
 advice.c                               |  2 +-
 sha1-name.c                            |  2 +-
 wt-status.c                            |  2 +-
 22 files changed, 88 insertions(+), 87 deletions(-)

Comments

Junio C Hamano Nov. 28, 2018, 6:04 a.m. UTC | #1
Nguyễn Thái Ngọc Duy  <pclouds@gmail.com> writes:

> The assumption made is here
>
> - "git checkout" is a horrible monster that should only be touched
>   with a two-meter pole
>
> - there are other commands that can achieve the same thing

Thanks for clearly spelling out the assumptions.  It is good that
this step cames at the end, as the earlier 6 steps looked reasonable
to me.

Thanks.


>
> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
> ---
>  Documentation/git-branch.txt           |  8 ++--
>  Documentation/git-check-ref-format.txt |  2 +-
>  Documentation/git-format-patch.txt     |  2 +-
>  Documentation/git-merge-base.txt       |  2 +-
>  Documentation/git-rebase.txt           |  2 +-
>  Documentation/git-remote.txt           |  2 +-
>  Documentation/git-rerere.txt           | 10 ++---
>  Documentation/git-reset.txt            | 18 ++++-----
>  Documentation/git-revert.txt           |  2 +-
>  Documentation/git-stash.txt            |  6 +--
>  Documentation/gitattributes.txt        |  2 +-
>  Documentation/gitcli.txt               |  4 +-
>  Documentation/gitcore-tutorial.txt     | 18 ++++-----
>  Documentation/giteveryday.txt          | 24 ++++++------
>  Documentation/githooks.txt             |  5 ++-
>  Documentation/gittutorial-2.txt        |  2 +-
>  Documentation/gittutorial.txt          |  4 +-
>  Documentation/revisions.txt            |  2 +-
>  Documentation/user-manual.txt          | 54 +++++++++++++-------------
>  advice.c                               |  2 +-
>  sha1-name.c                            |  2 +-
>  wt-status.c                            |  2 +-
>  22 files changed, 88 insertions(+), 87 deletions(-)
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index bf5316ffa9..1564df47d2 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -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-branch <newbranch>" to switch to the
>  new branch.
>  
>  When a local branch is started off a remote-tracking branch, Git sets up the
> @@ -194,7 +194,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-branch` 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.
>  
> @@ -293,7 +293,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-branch my2.6.14
>  ------------
>  +
>  <1> This step and the next one could be combined into a single step with
> @@ -319,7 +319,7 @@ 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
> +easier to use the "git switch-branch" command with its `-b` option to create
>  a branch and check it out with a single command.
>  
>  The options `--contains`, `--no-contains`, `--merged` and `--no-merged`
> diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
> index d9de992585..38c2169d7a 100644
> --- a/Documentation/git-check-ref-format.txt
> +++ b/Documentation/git-check-ref-format.txt
> @@ -88,7 +88,7 @@ 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-branch" 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
> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
> index aba4c5febe..0ceaa1173c 100644
> --- a/Documentation/git-format-patch.txt
> +++ b/Documentation/git-format-patch.txt
> @@ -416,7 +416,7 @@ 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 switch-branch test-apply
>      $ git reset --hard
>      $ git am a.patch
>  
> diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
> index 9f07f4f6ed..1b25e5d530 100644
> --- a/Documentation/git-merge-base.txt
> +++ b/Documentation/git-merge-base.txt
> @@ -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-branch -b
>  topic origin/master`, the history of remote-tracking branch
>  `origin/master` may have been rewound and rebuilt, leading to a
>  history of this shape:
> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
> index 80793bad8d..fe10880633 100644
> --- a/Documentation/git-rebase.txt
> +++ b/Documentation/git-rebase.txt
> @@ -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 <branch>` before doing anything else.  Otherwise
>  it remains on the current branch.
>  
>  If <upstream> is not specified, the upstream configured in
> diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
> index 0cad37fb81..044bbdb27c 100644
> --- a/Documentation/git-remote.txt
> +++ b/Documentation/git-remote.txt
> @@ -230,7 +230,7 @@ $ git branch -r
>    staging/master
>    staging/staging-linus
>    staging/staging-next
> -$ git checkout -b staging staging/master
> +$ git switch-branch -b staging staging/master
>  ...
>  ------------
>  
> diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
> index df310d2a58..fe9d21b395 100644
> --- a/Documentation/git-rerere.txt
> +++ b/Documentation/git-rerere.txt
> @@ -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-branch 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-branch topic
>  	$ git merge master
>  	$ ... work on both topic and master branches
> -	$ git checkout master
> +	$ git switch-branch 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-branch topic
>  	$ git merge master
>  	$ git reset --hard HEAD^ ;# rewind the test merge
>  	$ ... work on both topic and master branches
> -	$ git checkout master
> +	$ git switch-branch master
>  	$ git merge topic
>  
>                o---*---o-------o---o topic
> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
> index 2dac95c71a..ca46b4c967 100644
> --- a/Documentation/git-reset.txt
> +++ b/Documentation/git-reset.txt
> @@ -149,9 +149,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-branch topic/wip   <3>
>  ------------
>  +
>  <1> You have made some commits, but realize they were premature
> @@ -232,13 +232,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
> +$ git switch-branch 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-branch master
>  $ fix fix fix
>  $ git commit ;# commit with real log
> -$ git checkout feature
> +$ git switch-branch feature
>  $ git reset --soft HEAD^ ;# go back to WIP state  <2>
>  $ git reset                                       <3>
>  ------------
> @@ -279,18 +279,18 @@ reset it while keeping the changes in your working tree.
>  +
>  ------------
>  $ git tag start
> -$ git checkout -b branch1
> +$ git switch-branch -b branch1
>  $ edit
>  $ git commit ...                            <1>
>  $ edit
> -$ git checkout -b branch2                   <2>
> +$ git switch-branch -b 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-branch -b branch2 start"), but nobody is
>      perfect.
>  <3> But you can use "reset --keep" to remove the unwanted commit after
>      you switched to "branch2".
> diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
> index 837707a8fd..e49dbbec83 100644
> --- a/Documentation/git-revert.txt
> +++ b/Documentation/git-revert.txt
> @@ -26,7 +26,7 @@ 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
> +should see linkgit:git-checkout[1], specifically the `git checkout-files
>  <commit> -- <filename>` syntax.  Take care with these alternatives as
>  both will discard uncommitted changes in your working directory.
>  
> diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
> index 7ef8c47911..ea226979b1 100644
> --- a/Documentation/git-stash.txt
> +++ b/Documentation/git-stash.txt
> @@ -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-branch -b my_wip
>  $ git commit -a -m "WIP"
> -$ git checkout master
> +$ git switch-branch master
>  $ edit emergency fix
>  $ git commit -a -m "Fix in a hurry"
> -$ git checkout my_wip
> +$ git switch-branch my_wip
>  $ git reset --soft HEAD^
>  # ... continue hacking ...
>  ----------------------------------------------------------------
> diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
> index b8392fc330..df62bd8019 100644
> --- a/Documentation/gitattributes.txt
> +++ b/Documentation/gitattributes.txt
> @@ -112,7 +112,7 @@ Checking-out and checking-in
>  
>  These attributes affect how the contents stored in the
>  repository are copied to the working tree files when commands
> -such as 'git checkout' and 'git merge' run.  They also affect how
> +such as 'git switch-branch' and 'git merge' run.  They also affect how
>  Git stores the contents you prepare in the working tree in the
>  repository upon 'git add' and 'git commit'.
>  
> diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
> index 592e06d839..0ad4869f2c 100644
> --- a/Documentation/gitcli.txt
> +++ b/Documentation/gitcli.txt
> @@ -47,8 +47,8 @@ disambiguating `--` at appropriate places.
>     things:
>  +
>  --------------------------------
> -$ git checkout -- *.c
> -$ git checkout -- \*.c
> +$ git checkout-files -- *.c
> +$ git checkout-files -- \*.c
>  --------------------------------
>  +
>  The former lets your shell expand the fileglob, and you are asking
> diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
> index e29a9effcc..49a8b5aa52 100644
> --- a/Documentation/gitcore-tutorial.txt
> +++ b/Documentation/gitcore-tutorial.txt
> @@ -741,7 +741,7 @@ used earlier, and create a branch in it. You do that by simply just
>  saying that you want to check out a new branch:
>  
>  ------------
> -$ git checkout -b mybranch
> +$ git branch mybranch
>  ------------
>  
>  will create a new branch based at the current `HEAD` position, and switch
> @@ -755,7 +755,7 @@ just telling 'git checkout' what the base of the checkout would be.
>  In other words, if you have an earlier tag or branch, you'd just do
>  
>  ------------
> -$ git checkout -b mybranch earlier-commit
> +$ git switch-branch -b mybranch earlier-commit
>  ------------
>  
>  and it would create the new branch `mybranch` at the earlier commit,
> @@ -765,7 +765,7 @@ and check out the state at that time.
>  You can always just jump back to your original `master` branch by doing
>  
>  ------------
> -$ git checkout master
> +$ git switch-branch master
>  ------------
>  
>  (or any other branch-name, for that matter) and if you forget which
> @@ -794,7 +794,7 @@ $ git branch <branchname> [startingpoint]
>  
>  which will simply _create_ the branch, but will not do anything further.
>  You can then later -- once you decide that you want to actually develop
> -on that branch -- switch to that branch with a regular 'git checkout'
> +on that branch -- switch to that branch with a regular 'git switch-branch
>  with the branchname as the argument.
>  
>  
> @@ -808,7 +808,7 @@ being the same as the original `master` branch, let's make sure we're in
>  that branch, and do some work there.
>  
>  ------------------------------------------------
> -$ git checkout mybranch
> +$ git switch-branch mybranch
>  $ echo "Work, work, work" >>hello
>  $ git commit -m "Some work." -i hello
>  ------------------------------------------------
> @@ -825,7 +825,7 @@ does some work in the original branch, and simulate that by going back
>  to the master branch, and editing the same file differently there:
>  
>  ------------
> -$ git checkout master
> +$ git switch-branch master
>  ------------
>  
>  Here, take a moment to look at the contents of `hello`, and notice how they
> @@ -958,7 +958,7 @@ to the `master` branch. Let's go back to `mybranch`, and run
>  'git merge' to get the "upstream changes" back to your branch.
>  
>  ------------
> -$ git checkout mybranch
> +$ git switch-branch mybranch
>  $ git merge -m "Merge upstream changes." master
>  ------------
>  
> @@ -1133,9 +1133,9 @@ Remember, before running 'git merge', our `master` head was at
>  work." commit.
>  
>  ------------
> -$ git checkout mybranch
> +$ git switch-branch mybranch
>  $ git reset --hard master^2
> -$ git checkout master
> +$ git switch-branch master
>  $ git reset --hard master^
>  ------------
>  
> diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt
> index 9f2528fc8c..861b2bb616 100644
> --- a/Documentation/giteveryday.txt
> +++ b/Documentation/giteveryday.txt
> @@ -80,9 +80,9 @@ $ git tag v2.43 <2>
>  Create a topic branch and develop.::
>  +
>  ------------
> -$ git checkout -b alsa-audio <1>
> +$ git branch alsa-audio <1>
>  $ edit/compile/test
> -$ git checkout -- curses/ux_audio_oss.c <2>
> +$ git checkout-files -- curses/ux_audio_oss.c <2>
>  $ git add curses/ux_audio_alsa.c <3>
>  $ edit/compile/test
>  $ git diff HEAD <4>
> @@ -90,7 +90,7 @@ $ git commit -a -s <5>
>  $ edit/compile/test
>  $ git diff HEAD^ <6>
>  $ git commit -a --amend <7>
> -$ git checkout master <8>
> +$ git switch-branch master <8>
>  $ git merge alsa-audio <9>
>  $ git log --since='3 days ago' <10>
>  $ git log v2.43.. curses/ <11>
> @@ -148,11 +148,11 @@ Clone the upstream and work on it.  Feed changes to upstream.::
>  ------------
>  $ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
>  $ cd my2.6
> -$ git checkout -b mine master <1>
> +$ git switch-branch -b mine master <1>
>  $ edit/compile/test; git commit -a -s <2>
>  $ git format-patch master <3>
>  $ git send-email --to="person <email@example.com>" 00*.patch <4>
> -$ git checkout master <5>
> +$ git switch-branch master <5>
>  $ git pull <6>
>  $ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <7>
>  $ git ls-remote --heads http://git.kernel.org/.../jgarzik/libata-dev.git <8>
> @@ -194,7 +194,7 @@ satellite$ edit/compile/test/commit
>  satellite$ git push origin <4>
>  
>  mothership$ cd frotz
> -mothership$ git checkout master
> +mothership$ git switch-branch master
>  mothership$ git merge satellite/master <5>
>  ------------
>  +
> @@ -216,7 +216,7 @@ machine into the master branch.
>  Branch off of a specific tag.::
>  +
>  ------------
> -$ git checkout -b private2.6.14 v2.6.14 <1>
> +$ git switch-branch -b private2.6.14 v2.6.14 <1>
>  $ edit/compile/test; git commit -a
>  $ git checkout master
>  $ git cherry-pick v2.6.14..private2.6.14 <2>
> @@ -274,14 +274,14 @@ $ mailx <3>
>  & s 2 3 4 5 ./+to-apply
>  & s 7 8 ./+hold-linus
>  & q
> -$ git checkout -b topic/one master
> +$ git switch-branch -b topic/one master
>  $ git am -3 -i -s ./+to-apply <4>
>  $ compile/test
> -$ git checkout -b hold/linus && git am -3 -i -s ./+hold-linus <5>
> -$ git checkout topic/one && git rebase master <6>
> -$ git checkout pu && git reset --hard next <7>
> +$ git switch-branch -b hold/linus && git am -3 -i -s ./+hold-linus <5>
> +$ git switch-branch topic/one && git rebase master <6>
> +$ git switch-branch pu && git reset --hard next <7>
>  $ git merge topic/one topic/two && git merge hold/linus <8>
> -$ git checkout maint
> +$ git switch-branch maint
>  $ git cherry-pick master~4 <9>
>  $ compile/test
>  $ git tag -s -m "GIT 0.99.9x" v0.99.9x <10>
> diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
> index 959044347e..3939ec774a 100644
> --- a/Documentation/githooks.txt
> +++ b/Documentation/githooks.txt
> @@ -166,7 +166,7 @@ worktree.  The hook is given three parameters: the ref of the previous HEAD,
>  the ref of the new HEAD (which may or may not have changed), and a flag
>  indicating whether the checkout was a branch checkout (changing branches,
>  flag=1) or a file checkout (retrieving a file from the index, flag=0).
> -This hook cannot affect the outcome of `git checkout`.
> +This hook cannot affect the outcome of `git switch-branch` or `git checkout`.
>  
>  It is also run after linkgit:git-clone[1], unless the `--no-checkout` (`-n`) option is
>  used. The first parameter given to the hook is the null-ref, the second the
> @@ -402,7 +402,8 @@ exit with a zero status.
>  For example, the hook can simply run `git read-tree -u -m HEAD "$1"`
>  in order to emulate `git fetch` that is run in the reverse direction
>  with `git push`, as the two-tree form of `git read-tree -u -m` is
> -essentially the same as `git checkout` that switches branches while
> +essentially the same as `git switch-branch` or `git checkout`
> +that switches branches while
>  keeping the local changes in the working tree that do not interfere
>  with the difference between the branches.
>  
> diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt
> index e0976f6017..125213d951 100644
> --- a/Documentation/gittutorial-2.txt
> +++ b/Documentation/gittutorial-2.txt
> @@ -376,7 +376,7 @@ Changes to be committed:
>  
>  Changes not staged for commit:
>    (use "git add <file>..." to update what will be committed)
> -  (use "git checkout -- <file>..." to discard changes in working directory)
> +  (use "git checkout-files -- <file>..." to discard changes in working directory)
>  
>  	modified:   file.txt
>  
> diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
> index 242de31cb6..396e55c191 100644
> --- a/Documentation/gittutorial.txt
> +++ b/Documentation/gittutorial.txt
> @@ -207,7 +207,7 @@ automatically.  The asterisk marks the branch you are currently on;
>  type
>  
>  ------------------------------------------------
> -$ git checkout experimental
> +$ git switch-branch experimental
>  ------------------------------------------------
>  
>  to switch to the experimental branch.  Now edit a file, commit the
> @@ -216,7 +216,7 @@ change, and switch back to the master branch:
>  ------------------------------------------------
>  (edit file)
>  $ git commit -a
> -$ git checkout master
> +$ git switch-branch master
>  ------------------------------------------------
>  
>  Check that the change you made is no longer visible, since it was
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 72daa20e76..f55502cd50 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -115,7 +115,7 @@ Here's an example to make it more clear:
>  ------------------------------
>  $ git config push.default current
>  $ git config remote.pushdefault myfork
> -$ git checkout -b mybranch origin/master
> +$ git switch-branch -b mybranch origin/master
>  
>  $ git rev-parse --symbolic-full-name @{upstream}
>  refs/remotes/origin/master
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index eff7890274..56397e93d4 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -125,7 +125,7 @@ Create a new branch head pointing to one of these versions and check it
>  out using linkgit:git-checkout[1]:
>  
>  ------------------------------------------------
> -$ git checkout -b new v2.6.13
> +$ git switch-branch -b new v2.6.13
>  ------------------------------------------------
>  
>  The working directory then reflects the contents that the project had
> @@ -282,10 +282,10 @@ a summary of the commands:
>  	this command will fail with a warning.
>  `git branch -D <branch>`::
>  	delete the branch `<branch>` irrespective of its merged status.
> -`git checkout <branch>`::
> +`git switch-branch <branch>`::
>  	make the current branch `<branch>`, updating the working
>  	directory to reflect the version referenced by `<branch>`.
> -`git checkout -b <new> <start-point>`::
> +`git switch-branch -b <new> <start-point>`::
>  	create a new branch `<new>` referencing `<start-point>`, and
>  	check it out.
>  
> @@ -302,12 +302,12 @@ ref: refs/heads/master
>  Examining an old version without creating a new branch
>  ------------------------------------------------------
>  
> -The `git checkout` command normally expects a branch head, but will also
> +The `git switch-branch` command normally expects a branch head, but will also
>  accept an arbitrary commit; for example, you can check out the commit
>  referenced by a tag:
>  
>  ------------------------------------------------
> -$ git checkout v2.6.17
> +$ git switch-branch v2.6.17
>  Note: checking out 'v2.6.17'.
>  
>  You are in 'detached HEAD' state. You can look around, make experimental
> @@ -317,7 +317,7 @@ state without impacting any branches by performing another checkout.
>  If you want to create a new branch to retain commits you create, you may
>  do so (now or later) by using -b with the checkout command again. Example:
>  
> -  git checkout -b new_branch_name
> +  git switch-branch -b new_branch_name
>  
>  HEAD is now at 427abfa Linux v2.6.17
>  ------------------------------------------------
> @@ -373,7 +373,7 @@ You might want to build on one of these remote-tracking branches
>  on a branch of your own, just as you would for a tag:
>  
>  ------------------------------------------------
> -$ git checkout -b my-todo-copy origin/todo
> +$ git switch-branch -b my-todo-copy origin/todo
>  ------------------------------------------------
>  
>  You can also check out `origin/todo` directly to examine it or
> @@ -1523,12 +1523,12 @@ Checking out an old version of a file
>  
>  In the process of undoing a previous bad change, you may find it
>  useful to check out an older version of a particular file using
> -linkgit:git-checkout[1].  We've used `git checkout` before to switch
> +linkgit:git-checkout[1].  We've used `git switch-branch` before to switch
>  branches, but it has quite different behavior if it is given a path
>  name: the command
>  
>  -------------------------------------------------
> -$ git checkout HEAD^ path/to/file
> +$ git checkout-files HEAD^ path/to/file
>  -------------------------------------------------
>  
>  replaces path/to/file by the contents it had in the commit HEAD^, and
> @@ -2211,8 +2211,8 @@ $ git branch --track release origin/master
>  These can be easily kept up to date using linkgit:git-pull[1].
>  
>  -------------------------------------------------
> -$ git checkout test && git pull
> -$ git checkout release && git pull
> +$ git switch-branch test && git pull
> +$ git switch-branch release && git pull
>  -------------------------------------------------
>  
>  Important note!  If you have any local changes in these branches, then
> @@ -2264,7 +2264,7 @@ tested changes
>  2) help future bug hunters that use `git bisect` to find problems
>  
>  -------------------------------------------------
> -$ git checkout -b speed-up-spinlocks v2.6.35
> +$ git switch-branch -b speed-up-spinlocks v2.6.35
>  -------------------------------------------------
>  
>  Now you apply the patch(es), run some tests, and commit the change(s).  If
> @@ -2279,7 +2279,7 @@ When you are happy with the state of this change, you can merge it into the
>  "test" branch in preparation to make it public:
>  
>  -------------------------------------------------
> -$ git checkout test && git merge speed-up-spinlocks
> +$ git switch-branch test && git merge speed-up-spinlocks
>  -------------------------------------------------
>  
>  It is unlikely that you would have any conflicts here ... but you might if you
> @@ -2291,7 +2291,7 @@ see the value of keeping each patch (or patch series) in its own branch.  It
>  means that the patches can be moved into the `release` tree in any order.
>  
>  -------------------------------------------------
> -$ git checkout release && git merge speed-up-spinlocks
> +$ git switch-branch release && git merge speed-up-spinlocks
>  -------------------------------------------------
>  
>  After a while, you will have a number of branches, and despite the
> @@ -2358,7 +2358,7 @@ Here are some of the scripts that simplify all this even further.
>  
>  case "$1" in
>  test|release)
> -	git checkout $1 && git pull . origin
> +	git switch-branch $1 && git pull . origin
>  	;;
>  origin)
>  	before=$(git rev-parse refs/remotes/origin/master)
> @@ -2400,7 +2400,7 @@ test|release)
>  		echo $1 already merged into $2 1>&2
>  		exit 1
>  	fi
> -	git checkout $2 && git pull . $1
> +	git switch-branch $2 && git pull . $1
>  	;;
>  *)
>  	usage
> @@ -2512,7 +2512,7 @@ Suppose that you create a branch `mywork` on a remote-tracking branch
>  `origin`, and create some commits on top of it:
>  
>  -------------------------------------------------
> -$ git checkout -b mywork origin
> +$ git switch-branch -b mywork origin
>  $ vi file.txt
>  $ git commit
>  $ vi otherfile.txt
> @@ -2552,7 +2552,7 @@ commits without any merges, you may instead choose to use
>  linkgit:git-rebase[1]:
>  
>  -------------------------------------------------
> -$ git checkout mywork
> +$ git switch-branch mywork
>  $ git rebase origin
>  -------------------------------------------------
>  
> @@ -3668,13 +3668,13 @@ change within the submodule, and then update the superproject to reference the
>  new commit:
>  
>  -------------------------------------------------
> -$ git checkout master
> +$ git switch-branch master
>  -------------------------------------------------
>  
>  or
>  
>  -------------------------------------------------
> -$ git checkout -b fix-up
> +$ git switch-branch -b fix-up
>  -------------------------------------------------
>  
>  then
> @@ -4194,7 +4194,7 @@ start.
>  A good place to start is with the contents of the initial commit, with:
>  
>  ----------------------------------------------------
> -$ git checkout e83c5163
> +$ git switch-branch e83c5163
>  ----------------------------------------------------
>  
>  The initial revision lays the foundation for almost everything Git has
> @@ -4437,10 +4437,10 @@ Managing branches
>  -----------------
>  
>  -----------------------------------------------
> -$ git branch	     # list all local branches in this repo
> -$ git checkout test  # switch working directory to branch "test"
> -$ git branch new     # create branch "new" starting at current HEAD
> -$ git branch -d new  # delete branch "new"
> +$ git branch			# list all local branches in this repo
> +$ git switch-branch test	# switch working directory to branch "test"
> +$ git branch new		# create branch "new" starting at current HEAD
> +$ git branch -d new		# delete branch "new"
>  -----------------------------------------------
>  
>  Instead of basing a new branch on current HEAD (the default), use:
> @@ -4456,7 +4456,7 @@ $ git branch new test~10 # ten commits before tip of branch "test"
>  Create and switch to a new branch at the same time:
>  
>  -----------------------------------------------
> -$ git checkout -b new v2.6.15
> +$ git switch-branch -b new v2.6.15
>  -----------------------------------------------
>  
>  Update and examine branches from the repository you cloned from:
> @@ -4467,7 +4467,7 @@ $ git branch -r		# list
>    origin/master
>    origin/next
>    ...
> -$ git checkout -b masterwork origin/master
> +$ git switch-branch -b masterwork origin/master
>  -----------------------------------------------
>  
>  Fetch a branch from a different repository, and give it a new
> diff --git a/advice.c b/advice.c
> index 5f35656409..1befdb2163 100644
> --- a/advice.c
> +++ b/advice.c
> @@ -195,7 +195,7 @@ void detach_advice(const char *new_name)
>  	"state without impacting any branches by performing another checkout.\n\n"
>  	"If you want to create a new branch to retain commits you create, you may\n"
>  	"do so (now or later) by using -b with the checkout command again. Example:\n\n"
> -	"  git checkout -b <new-branch-name>\n\n");
> +	"  git branch <new-branch-name>\n\n");
>  
>  	fprintf(stderr, fmt, new_name);
>  }
> diff --git a/sha1-name.c b/sha1-name.c
> index faa60f69e3..4e4e14a45c 100644
> --- a/sha1-name.c
> +++ b/sha1-name.c
> @@ -771,7 +771,7 @@ static int get_oid_basic(const char *str, int len, struct object_id *oid,
>  	"because it will be ignored when you just specify 40-hex. These refs\n"
>  	"may be created by mistake. For example,\n"
>  	"\n"
> -	"  git checkout -b $br $(git rev-parse ...)\n"
> +	"  git switch-branch -b $br $(git rev-parse ...)\n"
>  	"\n"
>  	"where \"$br\" is somehow empty and a 40-hex ref is created. Please\n"
>  	"examine these refs and maybe delete them. Turn this message off by\n"
> diff --git a/wt-status.c b/wt-status.c
> index a24711374c..6266683926 100644
> --- a/wt-status.c
> +++ b/wt-status.c
> @@ -224,7 +224,7 @@ static void wt_longstatus_print_dirty_header(struct wt_status *s,
>  		status_printf_ln(s, c, _("  (use \"git add <file>...\" to update what will be committed)"));
>  	else
>  		status_printf_ln(s, c, _("  (use \"git add/rm <file>...\" to update what will be committed)"));
> -	status_printf_ln(s, c, _("  (use \"git checkout -- <file>...\" to discard changes in working directory)"));
> +	status_printf_ln(s, c, _("  (use \"git checkout-files <file>...\" to discard changes in working directory)"));
>  	if (has_dirty_submodules)
>  		status_printf_ln(s, c, _("  (commit or discard the untracked or modified content in submodules)"));
>  	status_printf_ln(s, c, "%s", "");
Duy Nguyen Nov. 28, 2018, 3:33 p.m. UTC | #2
On Wed, Nov 28, 2018 at 7:04 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Nguyễn Thái Ngọc Duy  <pclouds@gmail.com> writes:
>
> > The assumption made is here
> >
> > - "git checkout" is a horrible monster that should only be touched
> >   with a two-meter pole
> >
> > - there are other commands that can achieve the same thing
>
> Thanks for clearly spelling out the assumptions.  It is good that
> this step cames at the end, as the earlier 6 steps looked reasonable
> to me.

I see my deliberate attempt to provoke has failed :D Giving your view
of the new commands as "training wheels", I take it we still should
make them visible as much as possible, but we just not try to hide
"git checkout" as much (e.g. we mention both new and old commands,
instead of just mentioning the new one, when suggesting something)?
Junio C Hamano Nov. 29, 2018, 6:05 a.m. UTC | #3
Duy Nguyen <pclouds@gmail.com> writes:

> I see my deliberate attempt to provoke has failed :D Giving your view
> of the new commands as "training wheels", I take it we still should
> make them visible as much as possible, but we just not try to hide
> "git checkout" as much (e.g. we mention both new and old commands,
> instead of just mentioning the new one, when suggesting something)?

Yes, I do support the overall idea of learning two (or possibly
three) separate commands would help new users to form the right
mental model much sooner than learning one that can be used in
multiple ways.  Another possible approach could be to split the use
of "reset" that does not move "HEAD" into the same half of
"checkout" that does not move "HEAD", i.e. checkout-files.

Patch
diff mbox series

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index bf5316ffa9..1564df47d2 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -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-branch <newbranch>" to switch to the
 new branch.
 
 When a local branch is started off a remote-tracking branch, Git sets up the
@@ -194,7 +194,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-branch` 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.
 
@@ -293,7 +293,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-branch my2.6.14
 ------------
 +
 <1> This step and the next one could be combined into a single step with
@@ -319,7 +319,7 @@  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
+easier to use the "git switch-branch" command with its `-b` option to create
 a branch and check it out with a single command.
 
 The options `--contains`, `--no-contains`, `--merged` and `--no-merged`
diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
index d9de992585..38c2169d7a 100644
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.txt
@@ -88,7 +88,7 @@  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-branch" 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
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index aba4c5febe..0ceaa1173c 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -416,7 +416,7 @@  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 switch-branch test-apply
     $ git reset --hard
     $ git am a.patch
 
diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index 9f07f4f6ed..1b25e5d530 100644
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -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-branch -b
 topic origin/master`, the history of remote-tracking branch
 `origin/master` may have been rewound and rebuilt, leading to a
 history of this shape:
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 80793bad8d..fe10880633 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -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 <branch>` before doing anything else.  Otherwise
 it remains on the current branch.
 
 If <upstream> is not specified, the upstream configured in
diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index 0cad37fb81..044bbdb27c 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -230,7 +230,7 @@  $ git branch -r
   staging/master
   staging/staging-linus
   staging/staging-next
-$ git checkout -b staging staging/master
+$ git switch-branch -b staging staging/master
 ...
 ------------
 
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
index df310d2a58..fe9d21b395 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.txt
@@ -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-branch 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-branch topic
 	$ git merge master
 	$ ... work on both topic and master branches
-	$ git checkout master
+	$ git switch-branch 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-branch topic
 	$ git merge master
 	$ git reset --hard HEAD^ ;# rewind the test merge
 	$ ... work on both topic and master branches
-	$ git checkout master
+	$ git switch-branch master
 	$ git merge topic
 
               o---*---o-------o---o topic
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 2dac95c71a..ca46b4c967 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -149,9 +149,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-branch topic/wip   <3>
 ------------
 +
 <1> You have made some commits, but realize they were premature
@@ -232,13 +232,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
+$ git switch-branch 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-branch master
 $ fix fix fix
 $ git commit ;# commit with real log
-$ git checkout feature
+$ git switch-branch feature
 $ git reset --soft HEAD^ ;# go back to WIP state  <2>
 $ git reset                                       <3>
 ------------
@@ -279,18 +279,18 @@  reset it while keeping the changes in your working tree.
 +
 ------------
 $ git tag start
-$ git checkout -b branch1
+$ git switch-branch -b branch1
 $ edit
 $ git commit ...                            <1>
 $ edit
-$ git checkout -b branch2                   <2>
+$ git switch-branch -b 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-branch -b branch2 start"), but nobody is
     perfect.
 <3> But you can use "reset --keep" to remove the unwanted commit after
     you switched to "branch2".
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index 837707a8fd..e49dbbec83 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -26,7 +26,7 @@  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
+should see linkgit:git-checkout[1], specifically the `git checkout-files
 <commit> -- <filename>` syntax.  Take care with these alternatives as
 both will discard uncommitted changes in your working directory.
 
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 7ef8c47911..ea226979b1 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -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-branch -b my_wip
 $ git commit -a -m "WIP"
-$ git checkout master
+$ git switch-branch master
 $ edit emergency fix
 $ git commit -a -m "Fix in a hurry"
-$ git checkout my_wip
+$ git switch-branch my_wip
 $ git reset --soft HEAD^
 # ... continue hacking ...
 ----------------------------------------------------------------
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index b8392fc330..df62bd8019 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -112,7 +112,7 @@  Checking-out and checking-in
 
 These attributes affect how the contents stored in the
 repository are copied to the working tree files when commands
-such as 'git checkout' and 'git merge' run.  They also affect how
+such as 'git switch-branch' and 'git merge' run.  They also affect how
 Git stores the contents you prepare in the working tree in the
 repository upon 'git add' and 'git commit'.
 
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 592e06d839..0ad4869f2c 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -47,8 +47,8 @@  disambiguating `--` at appropriate places.
    things:
 +
 --------------------------------
-$ git checkout -- *.c
-$ git checkout -- \*.c
+$ git checkout-files -- *.c
+$ git checkout-files -- \*.c
 --------------------------------
 +
 The former lets your shell expand the fileglob, and you are asking
diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
index e29a9effcc..49a8b5aa52 100644
--- a/Documentation/gitcore-tutorial.txt
+++ b/Documentation/gitcore-tutorial.txt
@@ -741,7 +741,7 @@  used earlier, and create a branch in it. You do that by simply just
 saying that you want to check out a new branch:
 
 ------------
-$ git checkout -b mybranch
+$ git branch mybranch
 ------------
 
 will create a new branch based at the current `HEAD` position, and switch
@@ -755,7 +755,7 @@  just telling 'git checkout' what the base of the checkout would be.
 In other words, if you have an earlier tag or branch, you'd just do
 
 ------------
-$ git checkout -b mybranch earlier-commit
+$ git switch-branch -b mybranch earlier-commit
 ------------
 
 and it would create the new branch `mybranch` at the earlier commit,
@@ -765,7 +765,7 @@  and check out the state at that time.
 You can always just jump back to your original `master` branch by doing
 
 ------------
-$ git checkout master
+$ git switch-branch master
 ------------
 
 (or any other branch-name, for that matter) and if you forget which
@@ -794,7 +794,7 @@  $ git branch <branchname> [startingpoint]
 
 which will simply _create_ the branch, but will not do anything further.
 You can then later -- once you decide that you want to actually develop
-on that branch -- switch to that branch with a regular 'git checkout'
+on that branch -- switch to that branch with a regular 'git switch-branch
 with the branchname as the argument.
 
 
@@ -808,7 +808,7 @@  being the same as the original `master` branch, let's make sure we're in
 that branch, and do some work there.
 
 ------------------------------------------------
-$ git checkout mybranch
+$ git switch-branch mybranch
 $ echo "Work, work, work" >>hello
 $ git commit -m "Some work." -i hello
 ------------------------------------------------
@@ -825,7 +825,7 @@  does some work in the original branch, and simulate that by going back
 to the master branch, and editing the same file differently there:
 
 ------------
-$ git checkout master
+$ git switch-branch master
 ------------
 
 Here, take a moment to look at the contents of `hello`, and notice how they
@@ -958,7 +958,7 @@  to the `master` branch. Let's go back to `mybranch`, and run
 'git merge' to get the "upstream changes" back to your branch.
 
 ------------
-$ git checkout mybranch
+$ git switch-branch mybranch
 $ git merge -m "Merge upstream changes." master
 ------------
 
@@ -1133,9 +1133,9 @@  Remember, before running 'git merge', our `master` head was at
 work." commit.
 
 ------------
-$ git checkout mybranch
+$ git switch-branch mybranch
 $ git reset --hard master^2
-$ git checkout master
+$ git switch-branch master
 $ git reset --hard master^
 ------------
 
diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt
index 9f2528fc8c..861b2bb616 100644
--- a/Documentation/giteveryday.txt
+++ b/Documentation/giteveryday.txt
@@ -80,9 +80,9 @@  $ git tag v2.43 <2>
 Create a topic branch and develop.::
 +
 ------------
-$ git checkout -b alsa-audio <1>
+$ git branch alsa-audio <1>
 $ edit/compile/test
-$ git checkout -- curses/ux_audio_oss.c <2>
+$ git checkout-files -- curses/ux_audio_oss.c <2>
 $ git add curses/ux_audio_alsa.c <3>
 $ edit/compile/test
 $ git diff HEAD <4>
@@ -90,7 +90,7 @@  $ git commit -a -s <5>
 $ edit/compile/test
 $ git diff HEAD^ <6>
 $ git commit -a --amend <7>
-$ git checkout master <8>
+$ git switch-branch master <8>
 $ git merge alsa-audio <9>
 $ git log --since='3 days ago' <10>
 $ git log v2.43.. curses/ <11>
@@ -148,11 +148,11 @@  Clone the upstream and work on it.  Feed changes to upstream.::
 ------------
 $ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
 $ cd my2.6
-$ git checkout -b mine master <1>
+$ git switch-branch -b mine master <1>
 $ edit/compile/test; git commit -a -s <2>
 $ git format-patch master <3>
 $ git send-email --to="person <email@example.com>" 00*.patch <4>
-$ git checkout master <5>
+$ git switch-branch master <5>
 $ git pull <6>
 $ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <7>
 $ git ls-remote --heads http://git.kernel.org/.../jgarzik/libata-dev.git <8>
@@ -194,7 +194,7 @@  satellite$ edit/compile/test/commit
 satellite$ git push origin <4>
 
 mothership$ cd frotz
-mothership$ git checkout master
+mothership$ git switch-branch master
 mothership$ git merge satellite/master <5>
 ------------
 +
@@ -216,7 +216,7 @@  machine into the master branch.
 Branch off of a specific tag.::
 +
 ------------
-$ git checkout -b private2.6.14 v2.6.14 <1>
+$ git switch-branch -b private2.6.14 v2.6.14 <1>
 $ edit/compile/test; git commit -a
 $ git checkout master
 $ git cherry-pick v2.6.14..private2.6.14 <2>
@@ -274,14 +274,14 @@  $ mailx <3>
 & s 2 3 4 5 ./+to-apply
 & s 7 8 ./+hold-linus
 & q
-$ git checkout -b topic/one master
+$ git switch-branch -b topic/one master
 $ git am -3 -i -s ./+to-apply <4>
 $ compile/test
-$ git checkout -b hold/linus && git am -3 -i -s ./+hold-linus <5>
-$ git checkout topic/one && git rebase master <6>
-$ git checkout pu && git reset --hard next <7>
+$ git switch-branch -b hold/linus && git am -3 -i -s ./+hold-linus <5>
+$ git switch-branch topic/one && git rebase master <6>
+$ git switch-branch pu && git reset --hard next <7>
 $ git merge topic/one topic/two && git merge hold/linus <8>
-$ git checkout maint
+$ git switch-branch maint
 $ git cherry-pick master~4 <9>
 $ compile/test
 $ git tag -s -m "GIT 0.99.9x" v0.99.9x <10>
diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index 959044347e..3939ec774a 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -166,7 +166,7 @@  worktree.  The hook is given three parameters: the ref of the previous HEAD,
 the ref of the new HEAD (which may or may not have changed), and a flag
 indicating whether the checkout was a branch checkout (changing branches,
 flag=1) or a file checkout (retrieving a file from the index, flag=0).
-This hook cannot affect the outcome of `git checkout`.
+This hook cannot affect the outcome of `git switch-branch` or `git checkout`.
 
 It is also run after linkgit:git-clone[1], unless the `--no-checkout` (`-n`) option is
 used. The first parameter given to the hook is the null-ref, the second the
@@ -402,7 +402,8 @@  exit with a zero status.
 For example, the hook can simply run `git read-tree -u -m HEAD "$1"`
 in order to emulate `git fetch` that is run in the reverse direction
 with `git push`, as the two-tree form of `git read-tree -u -m` is
-essentially the same as `git checkout` that switches branches while
+essentially the same as `git switch-branch` or `git checkout`
+that switches branches while
 keeping the local changes in the working tree that do not interfere
 with the difference between the branches.
 
diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt
index e0976f6017..125213d951 100644
--- a/Documentation/gittutorial-2.txt
+++ b/Documentation/gittutorial-2.txt
@@ -376,7 +376,7 @@  Changes to be committed:
 
 Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
-  (use "git checkout -- <file>..." to discard changes in working directory)
+  (use "git checkout-files -- <file>..." to discard changes in working directory)
 
 	modified:   file.txt
 
diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
index 242de31cb6..396e55c191 100644
--- a/Documentation/gittutorial.txt
+++ b/Documentation/gittutorial.txt
@@ -207,7 +207,7 @@  automatically.  The asterisk marks the branch you are currently on;
 type
 
 ------------------------------------------------
-$ git checkout experimental
+$ git switch-branch experimental
 ------------------------------------------------
 
 to switch to the experimental branch.  Now edit a file, commit the
@@ -216,7 +216,7 @@  change, and switch back to the master branch:
 ------------------------------------------------
 (edit file)
 $ git commit -a
-$ git checkout master
+$ git switch-branch master
 ------------------------------------------------
 
 Check that the change you made is no longer visible, since it was
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 72daa20e76..f55502cd50 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -115,7 +115,7 @@  Here's an example to make it more clear:
 ------------------------------
 $ git config push.default current
 $ git config remote.pushdefault myfork
-$ git checkout -b mybranch origin/master
+$ git switch-branch -b mybranch origin/master
 
 $ git rev-parse --symbolic-full-name @{upstream}
 refs/remotes/origin/master
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index eff7890274..56397e93d4 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -125,7 +125,7 @@  Create a new branch head pointing to one of these versions and check it
 out using linkgit:git-checkout[1]:
 
 ------------------------------------------------
-$ git checkout -b new v2.6.13
+$ git switch-branch -b new v2.6.13
 ------------------------------------------------
 
 The working directory then reflects the contents that the project had
@@ -282,10 +282,10 @@  a summary of the commands:
 	this command will fail with a warning.
 `git branch -D <branch>`::
 	delete the branch `<branch>` irrespective of its merged status.
-`git checkout <branch>`::
+`git switch-branch <branch>`::
 	make the current branch `<branch>`, updating the working
 	directory to reflect the version referenced by `<branch>`.
-`git checkout -b <new> <start-point>`::
+`git switch-branch -b <new> <start-point>`::
 	create a new branch `<new>` referencing `<start-point>`, and
 	check it out.
 
@@ -302,12 +302,12 @@  ref: refs/heads/master
 Examining an old version without creating a new branch
 ------------------------------------------------------
 
-The `git checkout` command normally expects a branch head, but will also
+The `git switch-branch` command normally expects a branch head, but will also
 accept an arbitrary commit; for example, you can check out the commit
 referenced by a tag:
 
 ------------------------------------------------
-$ git checkout v2.6.17
+$ git switch-branch v2.6.17
 Note: checking out 'v2.6.17'.
 
 You are in 'detached HEAD' state. You can look around, make experimental
@@ -317,7 +317,7 @@  state without impacting any branches by performing another checkout.
 If you want to create a new branch to retain commits you create, you may
 do so (now or later) by using -b with the checkout command again. Example:
 
-  git checkout -b new_branch_name
+  git switch-branch -b new_branch_name
 
 HEAD is now at 427abfa Linux v2.6.17
 ------------------------------------------------
@@ -373,7 +373,7 @@  You might want to build on one of these remote-tracking branches
 on a branch of your own, just as you would for a tag:
 
 ------------------------------------------------
-$ git checkout -b my-todo-copy origin/todo
+$ git switch-branch -b my-todo-copy origin/todo
 ------------------------------------------------
 
 You can also check out `origin/todo` directly to examine it or
@@ -1523,12 +1523,12 @@  Checking out an old version of a file
 
 In the process of undoing a previous bad change, you may find it
 useful to check out an older version of a particular file using
-linkgit:git-checkout[1].  We've used `git checkout` before to switch
+linkgit:git-checkout[1].  We've used `git switch-branch` before to switch
 branches, but it has quite different behavior if it is given a path
 name: the command
 
 -------------------------------------------------
-$ git checkout HEAD^ path/to/file
+$ git checkout-files HEAD^ path/to/file
 -------------------------------------------------
 
 replaces path/to/file by the contents it had in the commit HEAD^, and
@@ -2211,8 +2211,8 @@  $ git branch --track release origin/master
 These can be easily kept up to date using linkgit:git-pull[1].
 
 -------------------------------------------------
-$ git checkout test && git pull
-$ git checkout release && git pull
+$ git switch-branch test && git pull
+$ git switch-branch release && git pull
 -------------------------------------------------
 
 Important note!  If you have any local changes in these branches, then
@@ -2264,7 +2264,7 @@  tested changes
 2) help future bug hunters that use `git bisect` to find problems
 
 -------------------------------------------------
-$ git checkout -b speed-up-spinlocks v2.6.35
+$ git switch-branch -b speed-up-spinlocks v2.6.35
 -------------------------------------------------
 
 Now you apply the patch(es), run some tests, and commit the change(s).  If
@@ -2279,7 +2279,7 @@  When you are happy with the state of this change, you can merge it into the
 "test" branch in preparation to make it public:
 
 -------------------------------------------------
-$ git checkout test && git merge speed-up-spinlocks
+$ git switch-branch test && git merge speed-up-spinlocks
 -------------------------------------------------
 
 It is unlikely that you would have any conflicts here ... but you might if you
@@ -2291,7 +2291,7 @@  see the value of keeping each patch (or patch series) in its own branch.  It
 means that the patches can be moved into the `release` tree in any order.
 
 -------------------------------------------------
-$ git checkout release && git merge speed-up-spinlocks
+$ git switch-branch release && git merge speed-up-spinlocks
 -------------------------------------------------
 
 After a while, you will have a number of branches, and despite the
@@ -2358,7 +2358,7 @@  Here are some of the scripts that simplify all this even further.
 
 case "$1" in
 test|release)
-	git checkout $1 && git pull . origin
+	git switch-branch $1 && git pull . origin
 	;;
 origin)
 	before=$(git rev-parse refs/remotes/origin/master)
@@ -2400,7 +2400,7 @@  test|release)
 		echo $1 already merged into $2 1>&2
 		exit 1
 	fi
-	git checkout $2 && git pull . $1
+	git switch-branch $2 && git pull . $1
 	;;
 *)
 	usage
@@ -2512,7 +2512,7 @@  Suppose that you create a branch `mywork` on a remote-tracking branch
 `origin`, and create some commits on top of it:
 
 -------------------------------------------------
-$ git checkout -b mywork origin
+$ git switch-branch -b mywork origin
 $ vi file.txt
 $ git commit
 $ vi otherfile.txt
@@ -2552,7 +2552,7 @@  commits without any merges, you may instead choose to use
 linkgit:git-rebase[1]:
 
 -------------------------------------------------
-$ git checkout mywork
+$ git switch-branch mywork
 $ git rebase origin
 -------------------------------------------------
 
@@ -3668,13 +3668,13 @@  change within the submodule, and then update the superproject to reference the
 new commit:
 
 -------------------------------------------------
-$ git checkout master
+$ git switch-branch master
 -------------------------------------------------
 
 or
 
 -------------------------------------------------
-$ git checkout -b fix-up
+$ git switch-branch -b fix-up
 -------------------------------------------------
 
 then
@@ -4194,7 +4194,7 @@  start.
 A good place to start is with the contents of the initial commit, with:
 
 ----------------------------------------------------
-$ git checkout e83c5163
+$ git switch-branch e83c5163
 ----------------------------------------------------
 
 The initial revision lays the foundation for almost everything Git has
@@ -4437,10 +4437,10 @@  Managing branches
 -----------------
 
 -----------------------------------------------
-$ git branch	     # list all local branches in this repo
-$ git checkout test  # switch working directory to branch "test"
-$ git branch new     # create branch "new" starting at current HEAD
-$ git branch -d new  # delete branch "new"
+$ git branch			# list all local branches in this repo
+$ git switch-branch test	# switch working directory to branch "test"
+$ git branch new		# create branch "new" starting at current HEAD
+$ git branch -d new		# delete branch "new"
 -----------------------------------------------
 
 Instead of basing a new branch on current HEAD (the default), use:
@@ -4456,7 +4456,7 @@  $ git branch new test~10 # ten commits before tip of branch "test"
 Create and switch to a new branch at the same time:
 
 -----------------------------------------------
-$ git checkout -b new v2.6.15
+$ git switch-branch -b new v2.6.15
 -----------------------------------------------
 
 Update and examine branches from the repository you cloned from:
@@ -4467,7 +4467,7 @@  $ git branch -r		# list
   origin/master
   origin/next
   ...
-$ git checkout -b masterwork origin/master
+$ git switch-branch -b masterwork origin/master
 -----------------------------------------------
 
 Fetch a branch from a different repository, and give it a new
diff --git a/advice.c b/advice.c
index 5f35656409..1befdb2163 100644
--- a/advice.c
+++ b/advice.c
@@ -195,7 +195,7 @@  void detach_advice(const char *new_name)
 	"state without impacting any branches by performing another checkout.\n\n"
 	"If you want to create a new branch to retain commits you create, you may\n"
 	"do so (now or later) by using -b with the checkout command again. Example:\n\n"
-	"  git checkout -b <new-branch-name>\n\n");
+	"  git branch <new-branch-name>\n\n");
 
 	fprintf(stderr, fmt, new_name);
 }
diff --git a/sha1-name.c b/sha1-name.c
index faa60f69e3..4e4e14a45c 100644
--- a/sha1-name.c
+++ b/sha1-name.c
@@ -771,7 +771,7 @@  static int get_oid_basic(const char *str, int len, struct object_id *oid,
 	"because it will be ignored when you just specify 40-hex. These refs\n"
 	"may be created by mistake. For example,\n"
 	"\n"
-	"  git checkout -b $br $(git rev-parse ...)\n"
+	"  git switch-branch -b $br $(git rev-parse ...)\n"
 	"\n"
 	"where \"$br\" is somehow empty and a 40-hex ref is created. Please\n"
 	"examine these refs and maybe delete them. Turn this message off by\n"
diff --git a/wt-status.c b/wt-status.c
index a24711374c..6266683926 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -224,7 +224,7 @@  static void wt_longstatus_print_dirty_header(struct wt_status *s,
 		status_printf_ln(s, c, _("  (use \"git add <file>...\" to update what will be committed)"));
 	else
 		status_printf_ln(s, c, _("  (use \"git add/rm <file>...\" to update what will be committed)"));
-	status_printf_ln(s, c, _("  (use \"git checkout -- <file>...\" to discard changes in working directory)"));
+	status_printf_ln(s, c, _("  (use \"git checkout-files <file>...\" to discard changes in working directory)"));
 	if (has_dirty_submodules)
 		status_printf_ln(s, c, _("  (commit or discard the untracked or modified content in submodules)"));
 	status_printf_ln(s, c, "%s", "");