1git-checkout(1) 2=============== 3 4NAME 5---- 6git-checkout - Switch branches or restore working tree files 7 8SYNOPSIS 9-------- 10[verse] 11'git checkout' [-q] [-f] [-m] [<branch>] 12'git checkout' [-q] [-f] [-m] --detach [<branch>] 13'git checkout' [-q] [-f] [-m] [--detach] <commit> 14'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] 15'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... 16'git checkout' [<tree-ish>] [--] <pathspec>... 17'git checkout' (-p|--patch) [<tree-ish>] [--] [<paths>...] 18 19DESCRIPTION 20----------- 21Updates files in the working tree to match the version in the index 22or the specified tree. If no paths are given, 'git checkout' will 23also update `HEAD` to set the specified branch as the current 24branch. 25 26'git checkout' [<branch>]:: 27 To prepare for working on `<branch>`, switch to it by updating 28 the index and the files in the working tree, and by pointing 29 `HEAD` at the branch. Local modifications to the files in the 30 working tree are kept, so that they can be committed to the 31 `<branch>`. 32+ 33If `<branch>` is not found but there does exist a tracking branch in 34exactly one remote (call it `<remote>`) with a matching name and 35`--no-guess` is not specified, treat as equivalent to 36+ 37------------ 38$ git checkout -b <branch> --track <remote>/<branch> 39------------ 40+ 41You could omit `<branch>`, in which case the command degenerates to 42"check out the current branch", which is a glorified no-op with 43rather expensive side-effects to show only the tracking information, 44if exists, for the current branch. 45 46'git checkout' -b|-B <new_branch> [<start point>]:: 47 48 Specifying `-b` causes a new branch to be created as if 49 linkgit:git-branch[1] were called and then checked out. In 50 this case you can use the `--track` or `--no-track` options, 51 which will be passed to 'git branch'. As a convenience, 52 `--track` without `-b` implies branch creation; see the 53 description of `--track` below. 54+ 55If `-B` is given, `<new_branch>` is created if it doesn't exist; otherwise, it 56is reset. This is the transactional equivalent of 57+ 58------------ 59$ git branch -f <branch> [<start point>] 60$ git checkout <branch> 61------------ 62+ 63that is to say, the branch is not reset/created unless "git checkout" is 64successful. 65 66'git checkout' --detach [<branch>]:: 67'git checkout' [--detach] <commit>:: 68 69 Prepare to work on top of `<commit>`, by detaching `HEAD` at it 70 (see "DETACHED HEAD" section), and updating the index and the 71 files in the working tree. Local modifications to the files 72 in the working tree are kept, so that the resulting working 73 tree will be the state recorded in the commit plus the local 74 modifications. 75+ 76When the `<commit>` argument is a branch name, the `--detach` option can 77be used to detach `HEAD` at the tip of the branch (`git checkout 78<branch>` would check out that branch without detaching `HEAD`). 79+ 80Omitting `<branch>` detaches `HEAD` at the tip of the current branch. 81 82'git checkout' [<tree-ish>] [--] <pathspec>...:: 83 84 Overwrite paths in the working tree by replacing with the 85 contents in the index or in the `<tree-ish>` (most often a 86 commit). When a `<tree-ish>` is given, the paths that 87 match the `<pathspec>` are updated both in the index and in 88 the working tree. 89+ 90The index may contain unmerged entries because of a previous failed merge. 91By default, if you try to check out such an entry from the index, the 92checkout operation will fail and nothing will be checked out. 93Using `-f` will ignore these unmerged entries. The contents from a 94specific side of the merge can be checked out of the index by 95using `--ours` or `--theirs`. With `-m`, changes made to the working tree 96file can be discarded to re-create the original conflicted merge result. 97 98'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]:: 99 This is similar to the "check out paths to the working tree 100 from either the index or from a tree-ish" mode described 101 above, but lets you use the interactive interface to show 102 the "diff" output and choose which hunks to use in the 103 result. See below for the description of `--patch` option. 104 105 106OPTIONS 107------- 108-q:: 109--quiet:: 110 Quiet, suppress feedback messages. 111 112--progress:: 113--no-progress:: 114 Progress status is reported on the standard error stream 115 by default when it is attached to a terminal, unless `--quiet` 116 is specified. This flag enables progress reporting even if not 117 attached to a terminal, regardless of `--quiet`. 118 119-f:: 120--force:: 121 When switching branches, proceed even if the index or the 122 working tree differs from `HEAD`. This is used to throw away 123 local changes. 124+ 125When checking out paths from the index, do not fail upon unmerged 126entries; instead, unmerged entries are ignored. 127 128--ours:: 129--theirs:: 130 When checking out paths from the index, check out stage #2 131 ('ours') or #3 ('theirs') for unmerged paths. 132+ 133Note that during `git rebase` and `git pull --rebase`, 'ours' and 134'theirs' may appear swapped; `--ours` gives the version from the 135branch the changes are rebased onto, while `--theirs` gives the 136version from the branch that holds your work that is being rebased. 137+ 138This is because `rebase` is used in a workflow that treats the 139history at the remote as the shared canonical one, and treats the 140work done on the branch you are rebasing as the third-party work to 141be integrated, and you are temporarily assuming the role of the 142keeper of the canonical history during the rebase. As the keeper of 143the canonical history, you need to view the history from the remote 144as `ours` (i.e. "our shared canonical history"), while what you did 145on your side branch as `theirs` (i.e. "one contributor's work on top 146of it"). 147 148-b <new_branch>:: 149 Create a new branch named `<new_branch>` and start it at 150 `<start_point>`; see linkgit:git-branch[1] for details. 151 152-B <new_branch>:: 153 Creates the branch `<new_branch>` and start it at `<start_point>`; 154 if it already exists, then reset it to `<start_point>`. This is 155 equivalent to running "git branch" with "-f"; see 156 linkgit:git-branch[1] for details. 157 158-t:: 159--track:: 160 When creating a new branch, set up "upstream" configuration. See 161 "--track" in linkgit:git-branch[1] for details. 162+ 163If no `-b` option is given, the name of the new branch will be 164derived from the remote-tracking branch, by looking at the local part of 165the refspec configured for the corresponding remote, and then stripping 166the initial part up to the "*". 167This would tell us to use `hack` as the local branch when branching 168off of `origin/hack` (or `remotes/origin/hack`, or even 169`refs/remotes/origin/hack`). If the given name has no slash, or the above 170guessing results in an empty name, the guessing is aborted. You can 171explicitly give a name with `-b` 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--guess:: 178--no-guess:: 179 If `<branch>` is not found but there does exist a tracking 180 branch in exactly one remote (call it `<remote>`) with a 181 matching name, treat as equivalent to 182+ 183------------ 184$ git checkout -b <branch> --track <remote>/<branch> 185------------ 186+ 187If the branch exists in multiple remotes and one of them is named by 188the `checkout.defaultRemote` configuration variable, we'll use that 189one for the purposes of disambiguation, even if the `<branch>` isn't 190unique across all remotes. Set it to 191e.g. `checkout.defaultRemote=origin` to always checkout remote 192branches from there if `<branch>` is ambiguous but exists on the 193'origin' remote. See also `checkout.defaultRemote` in 194linkgit:git-config[1]. 195+ 196Use `--no-guess` to disable this. 197 198-l:: 199 Create the new branch's reflog; see linkgit:git-branch[1] for 200 details. 201 202--detach:: 203 Rather than checking out a branch to work on it, check out a 204 commit for inspection and discardable experiments. 205 This is the default behavior of `git checkout <commit>` when 206 `<commit>` is not a branch name. See the "DETACHED HEAD" section 207 below for details. 208 209--orphan <new_branch>:: 210 Create a new 'orphan' branch, named `<new_branch>`, started from 211 `<start_point>` and switch to it. The first commit made on this 212 new branch will have no parents and it will be the root of a new 213 history totally disconnected from all the other branches and 214 commits. 215+ 216The index and the working tree are adjusted as if you had previously run 217`git checkout <start_point>`. This allows you to start a new history 218that records a set of paths similar to `<start_point>` by easily running 219`git commit -a` to make the root commit. 220+ 221This can be useful when you want to publish the tree from a commit 222without exposing its full history. You might want to do this to publish 223an open source branch of a project whose current tree is "clean", but 224whose full history contains proprietary or otherwise encumbered bits of 225code. 226+ 227If you want to start a disconnected history that records a set of paths 228that is totally different from the one of `<start_point>`, then you should 229clear the index and the working tree right after creating the orphan 230branch by running `git rm -rf .` from the top level of the working tree. 231Afterwards you will be ready to prepare your new files, repopulating the 232working tree, by copying them from elsewhere, extracting a tarball, etc. 233 234--ignore-skip-worktree-bits:: 235 In sparse checkout mode, `git checkout -- <paths>` would 236 update only entries matched by `<paths>` and sparse patterns 237 in `$GIT_DIR/info/sparse-checkout`. This option ignores 238 the sparse patterns and adds back any files in `<paths>`. 239 240-m:: 241--merge:: 242 When switching branches, 243 if you have local modifications to one or more files that 244 are different between the current branch and the branch to 245 which you are switching, the command refuses to switch 246 branches in order to preserve your modifications in context. 247 However, with this option, a three-way merge between the current 248 branch, your working tree contents, and the new branch 249 is done, and you will be on the new branch. 250+ 251When a merge conflict happens, the index entries for conflicting 252paths are left unmerged, and you need to resolve the conflicts 253and mark the resolved paths with `git add` (or `git rm` if the merge 254should result in deletion of the path). 255+ 256When checking out paths from the index, this option lets you recreate 257the conflicted merge in the specified paths. 258 259--conflict=<style>:: 260 The same as `--merge` option above, but changes the way the 261 conflicting hunks are presented, overriding the 262 `merge.conflictStyle` configuration variable. Possible values are 263 "merge" (default) and "diff3" (in addition to what is shown by 264 "merge" style, shows the original contents). 265 266-p:: 267--patch:: 268 Interactively select hunks in the difference between the 269 `<tree-ish>` (or the index, if unspecified) and the working 270 tree. The chosen hunks are then applied in reverse to the 271 working tree (and if a `<tree-ish>` was specified, the index). 272+ 273This means that you can use `git checkout -p` to selectively discard 274edits from your current working tree. See the ``Interactive Mode'' 275section of linkgit:git-add[1] to learn how to operate the `--patch` mode. 276+ 277Note that this option uses the no overlay mode by default (see also 278`--overlay`), and currently doesn't support overlay mode. 279 280--ignore-other-worktrees:: 281 `git checkout` refuses when the wanted ref is already checked 282 out by another worktree. This option makes it check the ref 283 out anyway. In other words, the ref can be held by more than one 284 worktree. 285 286--overwrite-ignore:: 287--no-overwrite-ignore:: 288 Silently overwrite ignored files when switching branches. This 289 is the default behavior. Use `--no-overwrite-ignore` to abort 290 the operation when the new branch contains ignored files. 291 292--recurse-submodules:: 293--no-recurse-submodules:: 294 Using `--recurse-submodules` will update the content of all initialized 295 submodules according to the commit recorded in the superproject. If 296 local modifications in a submodule would be overwritten the checkout 297 will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`) 298 is used, the work trees of submodules will not be updated. 299 Just like linkgit:git-submodule[1], this will detach `HEAD` of the 300 submodule. 301 302--overlay:: 303--no-overlay:: 304 In the default overlay mode, `git checkout` never 305 removes files from the index or the working tree. When 306 specifying `--no-overlay`, files that appear in the index and 307 working tree, but not in `<tree-ish>` are removed, to make them 308 match `<tree-ish>` exactly. 309 310<branch>:: 311 Branch to checkout; if it refers to a branch (i.e., a name that, 312 when prepended with "refs/heads/", is a valid ref), then that 313 branch is checked out. Otherwise, if it refers to a valid 314 commit, your `HEAD` becomes "detached" and you are no longer on 315 any branch (see below for details). 316+ 317You can use the `@{-N}` syntax to refer to the N-th last 318branch/commit checked out using "git checkout" operation. You may 319also specify `-` which is synonymous to `@{-1}`. 320+ 321As a special case, you may use `A...B` as a shortcut for the 322merge base of `A` and `B` if there is exactly one merge base. You can 323leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. 324 325<new_branch>:: 326 Name for the new branch. 327 328<start_point>:: 329 The name of a commit at which to start the new branch; see 330 linkgit:git-branch[1] for details. Defaults to `HEAD`. 331 332<tree-ish>:: 333 Tree to checkout from (when paths are given). If not specified, 334 the index will be used. 335 336 337 338DETACHED HEAD 339------------- 340`HEAD` normally refers to a named branch (e.g. `master`). Meanwhile, each 341branch refers to a specific commit. Let's look at a repo with three 342commits, one of them tagged, and with branch `master` checked out: 343 344------------ 345 HEAD (refers to branch 'master') 346 | 347 v 348a---b---c branch 'master' (refers to commit 'c') 349 ^ 350 | 351 tag 'v2.0' (refers to commit 'b') 352------------ 353 354When a commit is created in this state, the branch is updated to refer to 355the new commit. Specifically, 'git commit' creates a new commit `d`, whose 356parent is commit `c`, and then updates branch `master` to refer to new 357commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers 358to commit `d`: 359 360------------ 361$ edit; git add; git commit 362 363 HEAD (refers to branch 'master') 364 | 365 v 366a---b---c---d branch 'master' (refers to commit 'd') 367 ^ 368 | 369 tag 'v2.0' (refers to commit 'b') 370------------ 371 372It is sometimes useful to be able to checkout a commit that is not at 373the tip of any named branch, or even to create a new commit that is not 374referenced by a named branch. Let's look at what happens when we 375checkout commit `b` (here we show two ways this may be done): 376 377------------ 378$ git checkout v2.0 # or 379$ git checkout master^^ 380 381 HEAD (refers to commit 'b') 382 | 383 v 384a---b---c---d branch 'master' (refers to commit 'd') 385 ^ 386 | 387 tag 'v2.0' (refers to commit 'b') 388------------ 389 390Notice that regardless of which checkout command we use, `HEAD` now refers 391directly to commit `b`. This is known as being in detached `HEAD` state. 392It means simply that `HEAD` refers to a specific commit, as opposed to 393referring to a named branch. Let's see what happens when we create a commit: 394 395------------ 396$ edit; git add; git commit 397 398 HEAD (refers to commit 'e') 399 | 400 v 401 e 402 / 403a---b---c---d branch 'master' (refers to commit 'd') 404 ^ 405 | 406 tag 'v2.0' (refers to commit 'b') 407------------ 408 409There is now a new commit `e`, but it is referenced only by `HEAD`. We can 410of course add yet another commit in this state: 411 412------------ 413$ edit; git add; git commit 414 415 HEAD (refers to commit 'f') 416 | 417 v 418 e---f 419 / 420a---b---c---d branch 'master' (refers to commit 'd') 421 ^ 422 | 423 tag 'v2.0' (refers to commit 'b') 424------------ 425 426In fact, we can perform all the normal Git operations. But, let's look 427at what happens when we then checkout `master`: 428 429------------ 430$ git checkout master 431 432 HEAD (refers to branch 'master') 433 e---f | 434 / v 435a---b---c---d branch 'master' (refers to commit 'd') 436 ^ 437 | 438 tag 'v2.0' (refers to commit 'b') 439------------ 440 441It is important to realize that at this point nothing refers to commit 442`f`. Eventually commit `f` (and by extension commit `e`) will be deleted 443by the routine Git garbage collection process, unless we create a reference 444before that happens. If we have not yet moved away from commit `f`, 445any of these will create a reference to it: 446 447------------ 448$ git checkout -b foo <1> 449$ git branch foo <2> 450$ git tag foo <3> 451------------ 452 453<1> creates a new branch `foo`, which refers to commit `f`, and then 454 updates `HEAD` to refer to branch `foo`. In other words, we'll no longer 455 be in detached `HEAD` state after this command. 456 457<2> similarly creates a new branch `foo`, which refers to commit `f`, 458 but leaves `HEAD` detached. 459 460<3> creates a new tag `foo`, which refers to commit `f`, 461 leaving `HEAD` detached. 462 463If we have moved away from commit `f`, then we must first recover its object 464name (typically by using git reflog), and then we can create a reference to 465it. For example, to see the last two commits to which `HEAD` referred, we 466can use either of these commands: 467 468------------ 469$ git reflog -2 HEAD # or 470$ git log -g -2 HEAD 471------------ 472 473ARGUMENT DISAMBIGUATION 474----------------------- 475 476When there is only one argument given and it is not `--` (e.g. `git 477checkout abc`), and when the argument is both a valid `<tree-ish>` 478(e.g. a branch `abc` exists) and a valid `<pathspec>` (e.g. a file 479or a directory whose name is "abc" exists), Git would usually ask 480you to disambiguate. Because checking out a branch is so common an 481operation, however, `git checkout abc` takes "abc" as a `<tree-ish>` 482in such a situation. Use `git checkout -- <pathspec>` if you want 483to checkout these paths out of the index. 484 485EXAMPLES 486-------- 487 488. The following sequence checks out the `master` branch, reverts 489 the `Makefile` to two revisions back, deletes `hello.c` by 490 mistake, and gets it back from the index. 491+ 492------------ 493$ git checkout master <1> 494$ git checkout master~2 Makefile <2> 495$ rm -f hello.c 496$ git checkout hello.c <3> 497------------ 498+ 499<1> switch branch 500<2> take a file out of another commit 501<3> restore `hello.c` from the index 502+ 503If you want to check out _all_ C source files out of the index, 504you can say 505+ 506------------ 507$ git checkout -- '*.c' 508------------ 509+ 510Note the quotes around `*.c`. The file `hello.c` will also be 511checked out, even though it is no longer in the working tree, 512because the file globbing is used to match entries in the index 513(not in the working tree by the shell). 514+ 515If you have an unfortunate branch that is named `hello.c`, this 516step would be confused as an instruction to switch to that branch. 517You should instead write: 518+ 519------------ 520$ git checkout -- hello.c 521------------ 522 523. After working in the wrong branch, switching to the correct 524 branch would be done using: 525+ 526------------ 527$ git checkout mytopic 528------------ 529+ 530However, your "wrong" branch and correct `mytopic` branch may 531differ in files that you have modified locally, in which case 532the above checkout would fail like this: 533+ 534------------ 535$ git checkout mytopic 536error: You have local changes to 'frotz'; not switching branches. 537------------ 538+ 539You can give the `-m` flag to the command, which would try a 540three-way merge: 541+ 542------------ 543$ git checkout -m mytopic 544Auto-merging frotz 545------------ 546+ 547After this three-way merge, the local modifications are _not_ 548registered in your index file, so `git diff` would show you what 549changes you made since the tip of the new branch. 550 551. When a merge conflict happens during switching branches with 552 the `-m` option, you would see something like this: 553+ 554------------ 555$ git checkout -m mytopic 556Auto-merging frotz 557ERROR: Merge conflict in frotz 558fatal: merge program failed 559------------ 560+ 561At this point, `git diff` shows the changes cleanly merged as in 562the previous example, as well as the changes in the conflicted 563files. Edit and resolve the conflict and mark it resolved with 564`git add` as usual: 565+ 566------------ 567$ edit frotz 568$ git add frotz 569------------ 570 571SEE ALSO 572-------- 573linkgit:git-switch[1], 574linkgit:git-restore[1] 575 576GIT 577--- 578Part of the linkgit:git[1] suite