5e1a2e8c61
Add discussion section to git-checkout documentation and mention detached HEAD in repository-layout document. Signed-off-by: Junio C Hamano <junkio@cox.net>
207 lines
6.3 KiB
Plaintext
207 lines
6.3 KiB
Plaintext
git-checkout(1)
|
|
===============
|
|
|
|
NAME
|
|
----
|
|
git-checkout - Checkout and switch to a branch
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'git-checkout' [-f] [-b <new_branch> [-l]] [-m] [<branch>]
|
|
'git-checkout' [<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.
|
|
|
|
-l::
|
|
Create the new branch's ref log. This activates recording of
|
|
all changes to made the branch ref, enabling use of date
|
|
based sha1 expressions such as "<branchname>@{yesterday}".
|
|
|
|
-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.
|
|
+
|
|
When this parameter names a non-branch (but still a valid commit object),
|
|
your HEAD becomes 'detached'.
|
|
|
|
|
|
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 `-b` option, but starting from
|
|
version 1.5.0, the above command 'detaches' your HEAD from the
|
|
current branch and directly point at the commit named by the tag
|
|
(`v2.6.18` in the above example).
|
|
|
|
You can use usual 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.
|
|
|
|
The command would refuse to switch back to make sure that you do
|
|
not discard your temporary state by mistake when your detached
|
|
HEAD is not pointed at by any existing ref. If you did want to
|
|
save your state (e.g. "I was interested in the fifth commit from
|
|
the top of 'master' branch", or "I made two commits to fix minor
|
|
bugs while on a detached HEAD" -- and if you do not want to lose
|
|
these facts), you can create a new branch and switch to it with
|
|
`git checkout -b newbranch` so that you can keep building on
|
|
that state, or tag it first so that you can come back to it
|
|
later and switch to the branch you wanted to switch to with `git
|
|
tag that_state; git checkout master`. On the other hand, if you
|
|
did want to discard the temporary state, you can give `-f`
|
|
option (e.g. `git checkout -f master`) to override this
|
|
behaviour.
|
|
|
|
|
|
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
|
|
|