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