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>
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 0cd87dd..1e2d89b 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt
@@ -48,7 +48,7 @@ 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 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 @@ $ 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 @@ NOTES ----- -If you are creating a branch that you want to checkout immediately, it is -easier to use the git checkout command with its `-b` option to create -a branch and check it out with a single command. +If you are creating a branch that you want to switch to immediately, +it is easier to use the "git switch" command with its `-c` option to +do the same thing with a single command. The options `--contains`, `--no-contains`, `--merged` and `--no-merged` serve four related but different purposes:
diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index d9de992..ee6a414 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt
@@ -88,7 +88,8 @@ 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
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 1af85d4..0a24a56 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt
@@ -421,7 +421,7 @@ * Apply it: $ git fetch <project> master:test-apply - $ git checkout test-apply + $ git switch test-apply $ git reset --hard $ git am a.patch
diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index 9f07f4f..261d5c1 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt
@@ -149,7 +149,7 @@ 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:
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 6363d67..c742b73 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt
@@ -17,7 +17,7 @@ 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
diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 0cad37f..9659abb 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt
@@ -230,7 +230,7 @@ staging/master staging/staging-linus staging/staging-next -$ git checkout -b staging staging/master +$ git switch -c staging staging/master ... ------------
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index df310d2..fe4434a 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt
@@ -91,7 +91,7 @@ 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 @@ 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 @@ 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
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 132f8e5..cbf901e 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt
@@ -149,9 +149,9 @@ 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 +232,13 @@ 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 +279,18 @@ + ------------ $ 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`.
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 7ef8c47..ebb6282 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt
@@ -235,12 +235,12 @@ + ---------------------------------------------------------------- # ... 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 @@ 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 ---
diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index e29a9ef..f880d21 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt
@@ -741,7 +741,7 @@ saying that you want to check out a new branch: ------------ -$ git checkout -b mybranch +$ git switch -c mybranch ------------ will create a new branch based at the current `HEAD` position, and switch @@ -755,7 +755,7 @@ In other words, if you have an earlier tag or branch, you'd just do ------------ -$ git checkout -b mybranch earlier-commit +$ git switch -c mybranch earlier-commit ------------ and it would create the new branch `mybranch` at the earlier commit, @@ -765,7 +765,7 @@ You can always just jump back to your original `master` branch by doing ------------ -$ git checkout master +$ git switch master ------------ (or any other branch-name, for that matter) and if you forget which @@ -794,7 +794,7 @@ 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' with the branchname as the argument. @@ -808,7 +808,7 @@ that branch, and do some work there. ------------------------------------------------ -$ git checkout mybranch +$ git switch mybranch $ echo "Work, work, work" >>hello $ git commit -m "Some work." -i hello ------------------------------------------------ @@ -825,7 +825,7 @@ to the master branch, and editing the same file differently there: ------------ -$ git checkout master +$ git switch master ------------ Here, take a moment to look at the contents of `hello`, and notice how they @@ -958,7 +958,7 @@ 'git merge' to get the "upstream changes" back to your branch. ------------ -$ git checkout mybranch +$ git switch mybranch $ git merge -m "Merge upstream changes." master ------------ @@ -1133,9 +1133,8 @@ work." commit. ------------ -$ git checkout mybranch -$ git reset --hard master^2 -$ git checkout master +$ git switch -C mybranch master^2 +$ git switch master $ git reset --hard master^ ------------
diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt index 9f2528f..ad455f3 100644 --- a/Documentation/giteveryday.txt +++ b/Documentation/giteveryday.txt
@@ -41,7 +41,7 @@ * linkgit:git-log[1] to see what happened. - * linkgit:git-checkout[1] and linkgit:git-branch[1] to switch + * linkgit:git-switch[1] and linkgit:git-branch[1] to switch branches. * linkgit:git-add[1] to manage the index file. @@ -80,7 +80,7 @@ Create a topic branch and develop.:: + ------------ -$ git checkout -b alsa-audio <1> +$ git switch -c alsa-audio <1> $ edit/compile/test $ git checkout -- curses/ux_audio_oss.c <2> $ git add curses/ux_audio_alsa.c <3> @@ -90,7 +90,7 @@ $ edit/compile/test $ git diff HEAD^ <6> $ git commit -a --amend <7> -$ git checkout master <8> +$ git switch master <8> $ git merge alsa-audio <9> $ git log --since='3 days ago' <10> $ git log v2.43.. curses/ <11> @@ -148,11 +148,11 @@ ------------ $ 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 -c 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 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$ git push origin <4> mothership$ cd frotz -mothership$ git checkout master +mothership$ git switch master mothership$ git merge satellite/master <5> ------------ + @@ -216,7 +216,7 @@ Branch off of a specific tag.:: + ------------ -$ git checkout -b private2.6.14 v2.6.14 <1> +$ git switch -c 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 @@ & s 2 3 4 5 ./+to-apply & s 7 8 ./+hold-linus & q -$ git checkout -b topic/one master +$ git switch -c 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 -c hold/linus && git am -3 -i -s ./+hold-linus <5> +$ git switch topic/one && git rebase master <6> +$ git switch -C pu next <7> $ git merge topic/one topic/two && git merge hold/linus <8> -$ git checkout maint +$ git switch 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/gittutorial.txt b/Documentation/gittutorial.txt index 242de31..e6ad6b5 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt
@@ -207,7 +207,7 @@ type ------------------------------------------------ -$ git checkout experimental +$ git switch experimental ------------------------------------------------ to switch to the experimental branch. Now edit a file, commit the @@ -216,7 +216,7 @@ ------------------------------------------------ (edit file) $ git commit -a -$ git checkout master +$ git switch master ------------------------------------------------ Check that the change you made is no longer visible, since it was
diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt index ca11c7b..abc0dc6 100644 --- a/Documentation/gitworkflows.txt +++ b/Documentation/gitworkflows.txt
@@ -301,8 +301,7 @@ .Rewind and rebuild next [caption="Recipe: "] ===================================== -* `git checkout next` -* `git reset --hard master` +* `git switch -C next master` * `git merge ai/topic_in_next1` * `git merge ai/topic_in_next2` * ...
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 72daa20..a1c7a65 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt
@@ -115,7 +115,7 @@ ------------------------------ $ git config push.default current $ git config remote.pushdefault myfork -$ git checkout -b mybranch origin/master +$ git switch -c 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 eff7890..94799fa 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt
@@ -122,10 +122,10 @@ while heads are expected to advance as development progresses. Create a new branch head pointing to one of these versions and check it -out using linkgit:git-checkout[1]: +out using linkgit:git-switch[1]: ------------------------------------------------ -$ git checkout -b new v2.6.13 +$ git switch -c new v2.6.13 ------------------------------------------------ The working directory then reflects the contents that the project had @@ -282,10 +282,10 @@ 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>`:: make the current branch `<branch>`, updating the working directory to reflect the version referenced by `<branch>`. -`git checkout -b <new> <start-point>`:: +`git switch -c <new> <start-point>`:: create a new branch `<new>` referencing `<start-point>`, and check it out. @@ -302,22 +302,22 @@ Examining an old version without creating a new branch ------------------------------------------------------ -The `git checkout` 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: +The `git switch` command normally expects a branch head, but will also +accept an arbitrary commit when invoked with --detach; for example, +you can check out the commit referenced by a tag: ------------------------------------------------ -$ git checkout v2.6.17 +$ git switch --detach v2.6.17 Note: checking out 'v2.6.17'. You are in 'detached HEAD' state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this -state without impacting any branches by performing another checkout. +state without impacting any branches by performing another switch. 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: +do so (now or later) by using -c with the switch command again. Example: - git checkout -b new_branch_name + git switch -c new_branch_name HEAD is now at 427abfa Linux v2.6.17 ------------------------------------------------ @@ -373,7 +373,7 @@ on a branch of your own, just as you would for a tag: ------------------------------------------------ -$ git checkout -b my-todo-copy origin/todo +$ git switch -c my-todo-copy origin/todo ------------------------------------------------ You can also check out `origin/todo` directly to examine it or @@ -2211,8 +2211,8 @@ 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 test && git pull +$ git switch release && git pull ------------------------------------------------- Important note! If you have any local changes in these branches, then @@ -2264,7 +2264,7 @@ 2) help future bug hunters that use `git bisect` to find problems ------------------------------------------------- -$ git checkout -b speed-up-spinlocks v2.6.35 +$ git switch -c 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 @@ "test" branch in preparation to make it public: ------------------------------------------------- -$ git checkout test && git merge speed-up-spinlocks +$ git switch 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 @@ means that the patches can be moved into the `release` tree in any order. ------------------------------------------------- -$ git checkout release && git merge speed-up-spinlocks +$ git switch release && git merge speed-up-spinlocks ------------------------------------------------- After a while, you will have a number of branches, and despite the @@ -2512,7 +2512,7 @@ `origin`, and create some commits on top of it: ------------------------------------------------- -$ git checkout -b mywork origin +$ git switch -c mywork origin $ vi file.txt $ git commit $ vi otherfile.txt @@ -2552,7 +2552,7 @@ linkgit:git-rebase[1]: ------------------------------------------------- -$ git checkout mywork +$ git switch mywork $ git rebase origin ------------------------------------------------- @@ -3668,13 +3668,13 @@ new commit: ------------------------------------------------- -$ git checkout master +$ git switch master ------------------------------------------------- or ------------------------------------------------- -$ git checkout -b fix-up +$ git switch -c fix-up ------------------------------------------------- then @@ -4194,7 +4194,7 @@ A good place to start is with the contents of the initial commit, with: ---------------------------------------------------- -$ git checkout e83c5163 +$ git switch --detach e83c5163 ---------------------------------------------------- The initial revision lays the foundation for almost everything Git has @@ -4437,10 +4437,10 @@ ----------------- ----------------------------------------------- -$ 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 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 @@ Create and switch to a new branch at the same time: ----------------------------------------------- -$ git checkout -b new v2.6.15 +$ git switch -c new v2.6.15 ----------------------------------------------- Update and examine branches from the repository you cloned from: @@ -4467,7 +4467,7 @@ origin/master origin/next ... -$ git checkout -b masterwork origin/master +$ git switch -c masterwork origin/master ----------------------------------------------- Fetch a branch from a different repository, and give it a new
diff --git a/advice.c b/advice.c index b224825..24a7741 100644 --- a/advice.c +++ b/advice.c
@@ -191,20 +191,20 @@ void NORETURN die_conclude_merge(void) void detach_advice(const char *new_name) { const char *fmt = - _("Note: checking out '%s'.\n" + _("Note: switching to '%s'.\n" "\n" "You are in 'detached HEAD' state. You can look around, make experimental\n" "changes and commit them, and you can discard any commits you make in this\n" - "state without impacting any branches by performing another checkout.\n" + "state without impacting any branches by switching back to a branch.\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" + "do so (now or later) by using -c with the switch command. Example:\n" "\n" - " git checkout -b <new-branch-name>\n" + " git switch -c <new-branch-name>\n" "\n" - "Or undo this checkout with:\n" + "Or undo this operation with:\n" "\n" - " git checkout -\n" + " git switch -\n" "\n" "Turn off this advice by setting config variable advice.detachedHead to false\n\n");
diff --git a/sha1-name.c b/sha1-name.c index 6dda2c1..da0518c 100644 --- a/sha1-name.c +++ b/sha1-name.c
@@ -743,7 +743,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 -c $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/t/t2020-checkout-detach.sh b/t/t2020-checkout-detach.sh index 743c724..b748db9 100755 --- a/t/t2020-checkout-detach.sh +++ b/t/t2020-checkout-detach.sh
@@ -195,20 +195,20 @@ # The first detach operation is more chatty than the following ones. cat >1st_detach <<-EOF && - Note: checking out 'HEAD^'. + Note: switching to 'HEAD^'. You are in 'detached HEAD' state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this - state without impacting any branches by performing another checkout. + state without impacting any branches by switching back to a branch. 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: + do so (now or later) by using -c with the switch command. Example: - git checkout -b <new-branch-name> + git switch -c <new-branch-name> - Or undo this checkout with: + Or undo this operation with: - git checkout - + git switch - Turn off this advice by setting config variable advice.detachedHead to false @@ -277,20 +277,20 @@ # The first detach operation is more chatty than the following ones. cat >1st_detach <<-EOF && - Note: checking out 'HEAD^'. + Note: switching to 'HEAD^'. You are in 'detached HEAD' state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this - state without impacting any branches by performing another checkout. + state without impacting any branches by switching back to a branch. 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: + do so (now or later) by using -c with the switch command. Example: - git checkout -b <new-branch-name> + git switch -c <new-branch-name> - Or undo this checkout with: + Or undo this operation with: - git checkout - + git switch - Turn off this advice by setting config variable advice.detachedHead to false
diff --git a/unpack-trees.c b/unpack-trees.c index 22c41a3..5ff64a9 100644 --- a/unpack-trees.c +++ b/unpack-trees.c
@@ -313,7 +313,7 @@ static struct progress *get_progress(struct unpack_trees_options *o) total++; } - return start_delayed_progress(_("Checking out files"), total); + return start_delayed_progress(_("Updating files"), total); } static void setup_collided_checkout_detection(struct checkout *state,