1git-switch(1) 2============= 3 4NAME 5---- 6git-switch - Switch branches 7 8SYNOPSIS 9-------- 10[verse] 11'git switch' [<options>] [--no-guess] <branch> 12'git switch' [<options>] --detach [<start-point>] 13'git switch' [<options>] (-c|-C) <new-branch> [<start-point>] 14'git switch' [<options>] --orphan <new-branch> 15 16DESCRIPTION 17----------- 18Switch to a specified branch. The working tree and the index are 19updated to match the branch. All new commits will be added to the tip 20of this branch. 21 22Optionally a new branch could be created with either `-c`, `-C`, 23automatically from a remote branch of same name (see `--guess`), or 24detach the working tree from any branch with `--detach`, along with 25switching. 26 27Switching branches does not require a clean index and working tree 28(i.e. no differences compared to `HEAD`). The operation is aborted 29however if the operation leads to loss of local changes, unless told 30otherwise with `--discard-changes` or `--merge`. 31 32OPTIONS 33------- 34<branch>:: 35 Branch to switch to. 36 37<new-branch>:: 38 Name for the new branch. 39 40<start-point>:: 41 The starting point for the new branch. Specifying a 42 `<start-point>` allows you to create a branch based on some 43 other point in history than where HEAD currently points. (Or, 44 in the case of `--detach`, allows you to inspect and detach 45 from some other point.) 46+ 47You can use the `@{-N}` syntax to refer to the N-th last 48branch/commit switched to using "git switch" or "git checkout" 49operation. You may also specify `-` which is synonymous to `@{-1}`. 50This is often used to switch quickly between two branches, or to undo 51a branch switch by mistake. 52+ 53As a special case, you may use `A...B` as a shortcut for the merge 54base of `A` and `B` if there is exactly one merge base. You can leave 55out at most one of `A` and `B`, in which case it defaults to `HEAD`. 56 57-c <new-branch>:: 58--create <new-branch>:: 59 Create a new branch named `<new-branch>` starting at 60 `<start-point>` before switching to the branch. This is a 61 convenient shortcut for: 62+ 63------------ 64$ git branch <new-branch> 65$ git switch <new-branch> 66------------ 67 68-C <new-branch>:: 69--force-create <new-branch>:: 70 Similar to `--create` except that if `<new-branch>` already 71 exists, it will be reset to `<start-point>`. This is a 72 convenient shortcut for: 73+ 74------------ 75$ git branch -f <new-branch> 76$ git switch <new-branch> 77------------ 78 79-d:: 80--detach:: 81 Switch to a commit for inspection and discardable 82 experiments. See the "DETACHED HEAD" section in 83 linkgit:git-checkout[1] for details. 84 85--guess:: 86--no-guess:: 87 If `<branch>` is not found but there does exist a tracking 88 branch in exactly one remote (call it `<remote>`) with a 89 matching name, treat as equivalent to 90+ 91------------ 92$ git switch -c <branch> --track <remote>/<branch> 93------------ 94+ 95If the branch exists in multiple remotes and one of them is named by 96the `checkout.defaultRemote` configuration variable, we'll use that 97one for the purposes of disambiguation, even if the `<branch>` isn't 98unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin` 99to always checkout remote branches from there if `<branch>` is 100ambiguous but exists on the 'origin' remote. See also 101`checkout.defaultRemote` in linkgit:git-config[1]. 102+ 103`--guess` is the default behavior. Use `--no-guess` to disable it. 104 105-f:: 106--force:: 107 An alias for `--discard-changes`. 108 109--discard-changes:: 110 Proceed even if the index or the working tree differs from 111 `HEAD`. Both the index and working tree are restored to match 112 the switching target. If `--recurse-submodules` is specified, 113 submodule content is also restored to match the switching 114 target. This is used to throw away local changes. 115 116-m:: 117--merge:: 118 If you have local modifications to one or more files that are 119 different between the current branch and the branch to which 120 you are switching, the command refuses to switch branches in 121 order to preserve your modifications in context. However, 122 with this option, a three-way merge between the current 123 branch, your working tree contents, and the new branch is 124 done, and you will be on the new branch. 125+ 126When a merge conflict happens, the index entries for conflicting 127paths are left unmerged, and you need to resolve the conflicts 128and mark the resolved paths with `git add` (or `git rm` if the merge 129should result in deletion of the path). 130 131--conflict=<style>:: 132 The same as `--merge` option above, but changes the way the 133 conflicting hunks are presented, overriding the 134 `merge.conflictStyle` configuration variable. Possible values are 135 "merge" (default) and "diff3" (in addition to what is shown by 136 "merge" style, shows the original contents). 137 138-q:: 139--quiet:: 140 Quiet, suppress feedback messages. 141 142--progress:: 143--no-progress:: 144 Progress status is reported on the standard error stream 145 by default when it is attached to a terminal, unless `--quiet` 146 is specified. This flag enables progress reporting even if not 147 attached to a terminal, regardless of `--quiet`. 148 149-t:: 150--track:: 151 When creating a new branch, set up "upstream" configuration. 152 `-c` is implied. See `--track` in linkgit:git-branch[1] for 153 details. 154+ 155If no `-c` option is given, the name of the new branch will be derived 156from the remote-tracking branch, by looking at the local part of the 157refspec configured for the corresponding remote, and then stripping 158the initial part up to the "*". This would tell us to use `hack` as 159the local branch when branching off of `origin/hack` (or 160`remotes/origin/hack`, or even `refs/remotes/origin/hack`). If the 161given name has no slash, or the above guessing results in an empty 162name, the guessing is aborted. You can explicitly give a name with 163`-c` in such a case. 164 165--no-track:: 166 Do not set up "upstream" configuration, even if the 167 `branch.autoSetupMerge` configuration variable is true. 168 169--orphan <new-branch>:: 170 Create a new 'orphan' branch, named `<new-branch>`. All 171 tracked files are removed. 172 173--ignore-other-worktrees:: 174 `git switch` refuses when the wanted ref is already 175 checked out by another worktree. This option makes it check 176 the ref out anyway. In other words, the ref can be held by 177 more than one worktree. 178 179--recurse-submodules:: 180--no-recurse-submodules:: 181 Using `--recurse-submodules` will update the content of all 182 initialized submodules according to the commit recorded in the 183 superproject. If nothing (or `--no-recurse-submodules`) is 184 used, the work trees of submodules will not be updated. Just 185 like linkgit:git-submodule[1], this will detach `HEAD` of the 186 submodules. 187 188EXAMPLES 189-------- 190 191The following command switches to the "master" branch: 192 193------------ 194$ git switch master 195------------ 196 197After working in the wrong branch, switching to the correct branch 198would be done using: 199 200------------ 201$ git switch mytopic 202------------ 203 204However, your "wrong" branch and correct "mytopic" branch may differ 205in files that you have modified locally, in which case the above 206switch would fail like this: 207 208------------ 209$ git switch mytopic 210error: You have local changes to 'frotz'; not switching branches. 211------------ 212 213You can give the `-m` flag to the command, which would try a three-way 214merge: 215 216------------ 217$ git switch -m mytopic 218Auto-merging frotz 219------------ 220 221After this three-way merge, the local modifications are _not_ 222registered in your index file, so `git diff` would show you what 223changes you made since the tip of the new branch. 224 225To switch back to the previous branch before we switched to mytopic 226(i.e. "master" branch): 227 228------------ 229$ git switch - 230------------ 231 232You can grow a new branch from any commit. For example, switch to 233"HEAD~3" and create branch "fixup": 234 235------------ 236$ git switch -c fixup HEAD~3 237Switched to a new branch 'fixup' 238------------ 239 240If you want to start a new branch from a remote branch of the same 241name: 242 243------------ 244$ git switch new-topic 245Branch 'new-topic' set up to track remote branch 'new-topic' from 'origin' 246Switched to a new branch 'new-topic' 247------------ 248 249To check out commit `HEAD~3` for temporary inspection or experiment 250without creating a new branch: 251 252------------ 253$ git switch --detach HEAD~3 254HEAD is now at 9fc9555312 Merge branch 'cc/shared-index-permbits' 255------------ 256 257If it turns out whatever you have done is worth keeping, you can 258always create a new name for it (without switching away): 259 260------------ 261$ git switch -c good-surprises 262------------ 263 264SEE ALSO 265-------- 266linkgit:git-checkout[1], 267linkgit:git-branch[1] 268 269GIT 270--- 271Part of the linkgit:git[1] suite