Documentation/git-switch.txt

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