diff options
Diffstat (limited to 'Documentation/git-checkout.txt')
| -rw-r--r-- | Documentation/git-checkout.txt | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt new file mode 100644 index 0000000000..d82efc00d4 --- /dev/null +++ b/Documentation/git-checkout.txt @@ -0,0 +1,151 @@ +git-checkout(1) +=============== + +NAME +---- +git-checkout - Checkout and switch to a branch + +SYNOPSIS +-------- +[verse] +'git-checkout' [-f] [-b <new_branch>] [-m] [<branch>] +'git-checkout' [-m] [<branch>] <paths>... + +DESCRIPTION +----------- + +When <paths> are not given, this command switches branches by +updating the index and working tree to reflect the specified +branch, <branch>, and updating HEAD to be <branch> or, if +specified, <new_branch>. Using -b will cause <new_branch> to +be created. + +When <paths> are given, this command does *not* switch +branches. It updates the named paths in the working tree from +the index file (i.e. it runs `git-checkout-index -f -u`). In +this case, `-f` and `-b` options are meaningless and giving +either of them results in an error. <branch> argument can be +used to specify a specific tree-ish to update the index for the +given paths before updating the working tree. + + +OPTIONS +------- +-f:: + Force a re-read of everything. + +-b:: + Create a new branch named <new_branch> and start it at + <branch>. The new branch name must pass all checks defined + by gitlink:git-check-ref-format[1]. Some of these checks + may restrict the characters allowed in a branch name. + +-m:: + 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 update-index`. + +<new_branch>:: + Name for the new branch. + +<branch>:: + Branch to checkout; may be any object ID that resolves to a + commit. Defaults to 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 out a file out of other commit +<3> restore hello.c from HEAD of current branch ++ +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 a 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 locally modified, 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 +merge: warning: conflicts during merge +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 update-index` as usual: ++ +------------ +$ edit frotz +$ git update-index 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 gitlink:git[7] suite + |