diff options
Diffstat (limited to 'Documentation/git-checkout.txt')
| -rw-r--r-- | Documentation/git-checkout.txt | 275 |
1 files changed, 275 insertions, 0 deletions
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt new file mode 100644 index 0000000000..37c1810e3f --- /dev/null +++ b/Documentation/git-checkout.txt @@ -0,0 +1,275 @@ +git-checkout(1) +=============== + +NAME +---- +git-checkout - Checkout a branch or paths to the working tree + +SYNOPSIS +-------- +[verse] +'git checkout' [-q] [-f] [-m] [<branch>] +'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>] +'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... +'git checkout' --patch [<tree-ish>] [--] [<paths>...] + +DESCRIPTION +----------- + +When <paths> are not given, this command switches branches by +updating the index, working tree, and HEAD to reflect the specified +branch. + +If `-b` is given, a new branch is created and checked out, as if +linkgit:git-branch[1] were called; in this case you can +use the --track or --no-track options, which will be passed to `git +branch`. As a convenience, --track without `-b` implies branch +creation; see the description of --track below. + +When <paths> or --patch are given, this command does *not* switch +branches. It updates the named paths in the working tree from +the index file, or from a named <tree-ish> (most often a commit). In +this case, the `-b` and `--track` options are meaningless and giving +either of them results in an error. The <tree-ish> argument can be +used to specify a specific tree-ish (i.e. commit, tag or tree) +to update the index for the given paths before updating the +working tree. + +The index may contain unmerged entries after a failed merge. By +default, if you try to check out such an entry from the index, the +checkout operation will fail and nothing will be checked out. +Using -f will ignore these unmerged entries. The contents from a +specific side of the merge can be checked out of the index by +using --ours or --theirs. With -m, changes made to the working tree +file can be discarded to recreate the original conflicted merge result. + +OPTIONS +------- +-q:: +--quiet:: + Quiet, suppress feedback messages. + +-f:: +--force:: + When switching branches, proceed even if the index or the + working tree differs from HEAD. This is used to throw away + local changes. ++ +When checking out paths from the index, do not fail upon unmerged +entries; instead, unmerged entries are ignored. + +--ours:: +--theirs:: + When checking out paths from the index, check out stage #2 + ('ours') or #3 ('theirs') for unmerged paths. + +-b:: + Create a new branch named <new_branch> and start it at + <start_point>; see linkgit:git-branch[1] for details. + +-t:: +--track:: + When creating a new branch, set up "upstream" configuration. See + "--track" in linkgit:git-branch[1] for details. ++ +If no '-b' option is given, the name of the new branch will be +derived from the remote branch. If "remotes/" or "refs/remotes/" +is prefixed it is stripped away, and then the part up to the +next slash (which would be the nickname of the remote) is removed. +This would tell us to use "hack" as the local branch when branching +off of "origin/hack" (or "remotes/origin/hack", or even +"refs/remotes/origin/hack"). If the given name has no slash, or the above +guessing results in an empty name, the guessing is aborted. You can +explicitly give a name with '-b' in such a case. + +--no-track:: + Do not set up "upstream" configuration, even if the + branch.autosetupmerge configuration variable is true. + +-l:: + Create the new branch's reflog; see linkgit:git-branch[1] for + details. + +-m:: +--merge:: + When switching branches, + if you have local modifications to one or more files that + are different between the current branch and the branch to + which you are switching, the command refuses to switch + branches in order to preserve your modifications in context. + However, with this option, a three-way merge between the current + branch, your working tree contents, and the new branch + is done, and you will be on the new branch. ++ +When a merge conflict happens, the index entries for conflicting +paths are left unmerged, and you need to resolve the conflicts +and mark the resolved paths with `git add` (or `git rm` if the merge +should result in deletion of the path). ++ +When checking out paths from the index, this option lets you recreate +the conflicted merge in the specified paths. + +--conflict=<style>:: + The same as --merge option above, but changes the way the + conflicting hunks are presented, overriding the + merge.conflictstyle configuration variable. Possible values are + "merge" (default) and "diff3" (in addition to what is shown by + "merge" style, shows the original contents). + +-p:: +--patch:: + Interactively select hunks in the difference between the + <tree-ish> (or the index, if unspecified) and the working + tree. The chosen hunks are then applied in reverse to the + working tree (and if a <tree-ish> was specified, the index). ++ +This means that you can use `git checkout -p` to selectively discard +edits from your current working tree. + +<branch>:: + Branch to checkout; if it refers to a branch (i.e., a name that, + when prepended with "refs/heads/", is a valid ref), then that + branch is checked out. Otherwise, if it refers to a valid + commit, your HEAD becomes "detached" and you are no longer on + any branch (see below for details). ++ +As a special case, the `"@\{-N\}"` syntax for the N-th last branch +checks out the branch (instead of detaching). You may also specify +`-` which is synonymous with `"@\{-1\}"`. + +<new_branch>:: + Name for the new branch. + +<start_point>:: + The name of a commit at which to start the new branch; see + linkgit:git-branch[1] for details. Defaults to HEAD. + +<tree-ish>:: + Tree to checkout from (when paths are given). If not specified, + the index will be used. + + + +Detached HEAD +------------- + +It is sometimes useful to be able to 'checkout' a commit that is +not at the tip of one of your branches. The most obvious +example is to check out the commit at a tagged official release +point, like this: + +------------ +$ git checkout v2.6.18 +------------ + +Earlier versions of git did not allow this and asked you to +create a temporary branch using the `-b` option, but starting from +version 1.5.0, the above command 'detaches' your HEAD from the +current branch and directly points at the commit named by the tag +(`v2.6.18` in the example above). + +You can use all git commands while in this state. You can use +`git reset --hard $othercommit` to further move around, for +example. You can make changes and create a new commit on top of +a detached HEAD. You can even create a merge by using `git +merge $othercommit`. + +The state you are in while your HEAD is detached is not recorded +by any branch (which is natural --- you are not on any branch). +What this means is that you can discard your temporary commits +and merges by switching back to an existing branch (e.g. `git +checkout master`), and a later `git prune` or `git gc` would +garbage-collect them. If you did this by mistake, you can ask +the reflog for HEAD where you were, e.g. + +------------ +$ git log -g -2 HEAD +------------ + + +EXAMPLES +-------- + +. The following sequence checks out the `master` branch, reverts +the `Makefile` to two revisions back, deletes hello.c by +mistake, and gets it back from the index. ++ +------------ +$ git checkout master <1> +$ git checkout master~2 Makefile <2> +$ rm -f hello.c +$ git checkout hello.c <3> +------------ ++ +<1> switch branch +<2> take a file out of another commit +<3> restore hello.c from the index ++ +If you have an unfortunate branch that is named `hello.c`, this +step would be confused as an instruction to switch to that branch. +You should instead write: ++ +------------ +$ git checkout -- hello.c +------------ + +. After working in the wrong branch, switching to the correct +branch would be done using: ++ +------------ +$ git checkout mytopic +------------ ++ +However, your "wrong" branch and correct "mytopic" branch may +differ in files that you have modified locally, in which case +the above checkout would fail like this: ++ +------------ +$ git checkout mytopic +fatal: Entry 'frotz' not uptodate. Cannot merge. +------------ ++ +You can give the `-m` flag to the command, which would try a +three-way merge: ++ +------------ +$ git checkout -m mytopic +Auto-merging frotz +------------ ++ +After this three-way merge, the local modifications are _not_ +registered in your index file, so `git diff` would show you what +changes you made since the tip of the new branch. + +. When a merge conflict happens during switching branches with +the `-m` option, you would see something like this: ++ +------------ +$ git checkout -m mytopic +Auto-merging frotz +ERROR: Merge conflict in frotz +fatal: merge program failed +------------ ++ +At this point, `git diff` shows the changes cleanly merged as in +the previous example, as well as the changes in the conflicted +files. Edit and resolve the conflict and mark it resolved with +`git add` as usual: ++ +------------ +$ edit frotz +$ git add frotz +------------ + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the linkgit:git[1] suite |