Skip to content

Commit 328c6cb

Browse files
pcloudsgitster
pclouds
authored and
gitster
committed
doc: promote "git switch"
The new command "git switch" is added to avoid the confusion of one-command-do-all "git checkout" for new users. They are also helpful to avoid ambiguation context. For these reasons, promote it everywhere possible. This includes documentation, suggestions/advice from other commands... The "Checking out files" progress line in unpack-trees.c is also updated to "Updating files" to be neutral to both git-checkout and git-switch. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
1 parent ae36fe6 commit 328c6cb

19 files changed

+105
-105
lines changed

‎Documentation/git-branch.txt‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ The command's second form creates a new branch head named <branchname>
4848
which points to the current `HEAD`, or <start-point> if given.
4949

5050
Note that this will create the new branch, but it will not switch the
51-
working tree to it; use "git checkout <newbranch>" to switch to the
51+
working tree to it; use "git switch <newbranch>" to switch to the
5252
new branch.
5353

5454
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.
198198
+
199199
This behavior is the default when the start point is a remote-tracking branch.
200200
Set the branch.autoSetupMerge configuration variable to `false` if you
201-
want `git checkout` and `git branch` to always behave as if `--no-track`
201+
want `git switch`, `git checkout` and `git branch` to always behave as if `--no-track`
202202
were given. Set it to `always` if you want this behavior when the
203203
start-point is either a local or remote-tracking branch.
204204

@@ -297,7 +297,7 @@ Start development from a known tag::
297297
$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
298298
$ cd my2.6
299299
$ git branch my2.6.14 v2.6.14 <1>
300-
$ git checkout my2.6.14
300+
$ git switch my2.6.14
301301
------------
302302
+
303303
<1> This step and the next one could be combined into a single step with
@@ -322,9 +322,9 @@ $ git branch -D test <2>
322322
NOTES
323323
-----
324324

325-
If you are creating a branch that you want to checkout immediately, it is
326-
easier to use the git checkout command with its `-b` option to create
327-
a branch and check it out with a single command.
325+
If you are creating a branch that you want to switch to immediately,
326+
it is easier to use the "git switch" command with its `-c` option to
327+
do the same thing with a single command.
328328

329329
The options `--contains`, `--no-contains`, `--merged` and `--no-merged`
330330
serve four related but different purposes:

‎Documentation/git-check-ref-format.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,8 @@ but it is explicitly forbidden at the beginning of a branch name).
8888
When run with `--branch` option in a repository, the input is first
8989
expanded for the ``previous checkout syntax''
9090
`@{-n}`. For example, `@{-1}` is a way to refer the last thing that
91-
was checked out using "git checkout" operation. This option should be
91+
was checked out using "git switch" or "git checkout" operation.
92+
This option should be
9293
used by porcelains to accept this syntax anywhere a branch name is
9394
expected, so they can act as if you typed the branch name. As an
9495
exception note that, the ``previous checkout operation'' might result

‎Documentation/git-format-patch.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -421,7 +421,7 @@ One way to test if your MUA is set up correctly is:
421421
* Apply it:
422422

423423
$ git fetch <project> master:test-apply
424-
$ git checkout test-apply
424+
$ git switch test-apply
425425
$ git reset --hard
426426
$ git am a.patch
427427

‎Documentation/git-merge-base.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,7 @@ instead.
149149
Discussion on fork-point mode
150150
-----------------------------
151151

152-
After working on the `topic` branch created with `git checkout -b
152+
After working on the `topic` branch created with `git switch -c
153153
topic origin/master`, the history of remote-tracking branch
154154
`origin/master` may have been rewound and rebuilt, leading to a
155155
history of this shape:

‎Documentation/git-rebase.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ SYNOPSIS
1717
DESCRIPTION
1818
-----------
1919
If <branch> is specified, 'git rebase' will perform an automatic
20-
`git checkout <branch>` before doing anything else. Otherwise
20+
`git switch <branch>` before doing anything else. Otherwise
2121
it remains on the current branch.
2222

2323
If <upstream> is not specified, the upstream configured in

‎Documentation/git-remote.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -230,7 +230,7 @@ $ git branch -r
230230
staging/master
231231
staging/staging-linus
232232
staging/staging-next
233-
$ git checkout -b staging staging/master
233+
$ git switch -c staging staging/master
234234
...
235235
------------
236236

‎Documentation/git-rerere.txt‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ For such a test, you need to merge master and topic somehow.
9191
One way to do it is to pull master into the topic branch:
9292

9393
------------
94-
$ git checkout topic
94+
$ git switch topic
9595
$ git merge master
9696

9797
o---*---o---+ topic
@@ -113,10 +113,10 @@ the upstream might have been advanced since the test merge `+`,
113113
in which case the final commit graph would look like this:
114114

115115
------------
116-
$ git checkout topic
116+
$ git switch topic
117117
$ git merge master
118118
$ ... work on both topic and master branches
119-
$ git checkout master
119+
$ git switch master
120120
$ git merge topic
121121

122122
o---*---o---+---o---o topic
@@ -136,11 +136,11 @@ merges, you could blow away the test merge, and keep building on
136136
top of the tip before the test merge:
137137

138138
------------
139-
$ git checkout topic
139+
$ git switch topic
140140
$ git merge master
141141
$ git reset --hard HEAD^ ;# rewind the test merge
142142
$ ... work on both topic and master branches
143-
$ git checkout master
143+
$ git switch master
144144
$ git merge topic
145145

146146
o---*---o-------o---o topic

‎Documentation/git-reset.txt‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -149,9 +149,9 @@ See also the `--amend` option to linkgit:git-commit[1].
149149
Undo a commit, making it a topic branch::
150150
+
151151
------------
152-
$ git branch topic/wip <1>
153-
$ git reset --hard HEAD~3 <2>
154-
$ git checkout topic/wip <3>
152+
$ git branch topic/wip <1>
153+
$ git reset --hard HEAD~3 <2>
154+
$ git switch topic/wip <3>
155155
------------
156156
+
157157
<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
232232
need to get to the other branch for a quick bugfix.
233233
+
234234
------------
235-
$ git checkout feature ;# you were working in "feature" branch and
236-
$ work work work ;# got interrupted
235+
$ git switch feature ;# you were working in "feature" branch and
236+
$ work work work ;# got interrupted
237237
$ git commit -a -m "snapshot WIP" <1>
238-
$ git checkout master
238+
$ git switch master
239239
$ fix fix fix
240240
$ git commit ;# commit with real log
241-
$ git checkout feature
241+
$ git switch feature
242242
$ git reset --soft HEAD^ ;# go back to WIP state <2>
243243
$ git reset <3>
244244
------------
@@ -279,18 +279,18 @@ reset it while keeping the changes in your working tree.
279279
+
280280
------------
281281
$ git tag start
282-
$ git checkout -b branch1
282+
$ git switch -c branch1
283283
$ edit
284284
$ git commit ... <1>
285285
$ edit
286-
$ git checkout -b branch2 <2>
286+
$ git switch -c branch2 <2>
287287
$ git reset --keep start <3>
288288
------------
289289
+
290290
<1> This commits your first edits in `branch1`.
291291
<2> In the ideal world, you could have realized that the earlier
292292
commit did not belong to the new topic when you created and switched
293-
to `branch2` (i.e. `git checkout -b branch2 start`), but nobody is
293+
to `branch2` (i.e. `git switch -c branch2 start`), but nobody is
294294
perfect.
295295
<3> But you can use `reset --keep` to remove the unwanted commit after
296296
you switched to `branch2`.

‎Documentation/git-stash.txt‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -235,12 +235,12 @@ return to your original branch to make the emergency fix, like this:
235235
+
236236
----------------------------------------------------------------
237237
# ... hack hack hack ...
238-
$ git checkout -b my_wip
238+
$ git switch -c my_wip
239239
$ git commit -a -m "WIP"
240-
$ git checkout master
240+
$ git switch master
241241
$ edit emergency fix
242242
$ git commit -a -m "Fix in a hurry"
243-
$ git checkout my_wip
243+
$ git switch my_wip
244244
$ git reset --soft HEAD^
245245
# ... continue hacking ...
246246
----------------------------------------------------------------
@@ -293,7 +293,8 @@ SEE ALSO
293293
linkgit:git-checkout[1],
294294
linkgit:git-commit[1],
295295
linkgit:git-reflog[1],
296-
linkgit:git-reset[1]
296+
linkgit:git-reset[1],
297+
linkgit:git-switch[1]
297298

298299
GIT
299300
---

‎Documentation/gitcore-tutorial.txt‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -741,7 +741,7 @@ used earlier, and create a branch in it. You do that by simply just
741741
saying that you want to check out a new branch:
742742

743743
------------
744-
$ git checkout -b mybranch
744+
$ git switch -c mybranch
745745
------------
746746

747747
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.
755755
In other words, if you have an earlier tag or branch, you'd just do
756756

757757
------------
758-
$ git checkout -b mybranch earlier-commit
758+
$ git switch -c mybranch earlier-commit
759759
------------
760760

761761
and it would create the new branch `mybranch` at the earlier commit,
@@ -765,7 +765,7 @@ and check out the state at that time.
765765
You can always just jump back to your original `master` branch by doing
766766

767767
------------
768-
$ git checkout master
768+
$ git switch master
769769
------------
770770

771771
(or any other branch-name, for that matter) and if you forget which
@@ -794,7 +794,7 @@ $ git branch <branchname> [startingpoint]
794794

795795
which will simply _create_ the branch, but will not do anything further.
796796
You can then later -- once you decide that you want to actually develop
797-
on that branch -- switch to that branch with a regular 'git checkout'
797+
on that branch -- switch to that branch with a regular 'git switch'
798798
with the branchname as the argument.
799799

800800

@@ -808,7 +808,7 @@ being the same as the original `master` branch, let's make sure we're in
808808
that branch, and do some work there.
809809

810810
------------------------------------------------
811-
$ git checkout mybranch
811+
$ git switch mybranch
812812
$ echo "Work, work, work" >>hello
813813
$ git commit -m "Some work." -i hello
814814
------------------------------------------------
@@ -825,7 +825,7 @@ does some work in the original branch, and simulate that by going back
825825
to the master branch, and editing the same file differently there:
826826

827827
------------
828-
$ git checkout master
828+
$ git switch master
829829
------------
830830

831831
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
958958
'git merge' to get the "upstream changes" back to your branch.
959959

960960
------------
961-
$ git checkout mybranch
961+
$ git switch mybranch
962962
$ git merge -m "Merge upstream changes." master
963963
------------
964964

@@ -1133,9 +1133,8 @@ Remember, before running 'git merge', our `master` head was at
11331133
work." commit.
11341134

11351135
------------
1136-
$ git checkout mybranch
1137-
$ git reset --hard master^2
1138-
$ git checkout master
1136+
$ git switch -C mybranch master^2
1137+
$ git switch master
11391138
$ git reset --hard master^
11401139
------------
11411140

0 commit comments

Comments
 (0)