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