X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-checkout.txt;h=918d8ee720a573f91ec6efa654da5c2cdc05d7b0;hb=9e2163ea45b688e9de4744ebb9b01ea7e1ed8d56;hp=fbdbadc74fbe558285323353b7aa006f3cfd559b;hpb=7fb23e6083dbefa8eb4c554d8b2cd5a6292b2df4;p=git.git diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index fbdbadc74..918d8ee72 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -8,8 +8,8 @@ git-checkout - Checkout and switch to a branch SYNOPSIS -------- [verse] -'git-checkout' [-f] [-b [-l]] [-m] [] -'git-checkout' [-m] [] ... +'git-checkout' [-q] [-f] [[--track | --no-track] -b [-l]] [-m] [] +'git-checkout' [] ... DESCRIPTION ----------- @@ -18,21 +18,28 @@ When are not given, this command switches branches by updating the index and working tree to reflect the specified branch, , and updating HEAD to be or, if specified, . Using -b will cause to -be created. +be created; in this case you can use the --track or --no-track +options, which will be passed to `git branch`. When 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. argument can be -used to specify a specific tree-ish to update the index for the -given paths before updating the working tree. +the index file (i.e. it runs `git-checkout-index -f -u`), or +from a named commit. In +this case, the `-f` and `-b` options are meaningless and giving +either of them results in an error. 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. OPTIONS ------- +-q:: + Quiet, supress feedback messages. + -f:: - Force a re-read of everything. + Proceed even if the index or the working tree differs + from HEAD. This is used to throw away local changes. -b:: Create a new branch named and start it at @@ -40,6 +47,20 @@ OPTIONS by gitlink:git-check-ref-format[1]. Some of these checks may restrict the characters allowed in a branch name. +--track:: + When -b is given and a branch is created off a remote branch, + set up configuration so that git-pull will automatically + retrieve data from the remote branch. Set the + branch.autosetupmerge configuration variable to true if you + want git-checkout and git-branch to always behave as if + '--track' were given. + +--no-track:: + When -b is given and a branch is created off a remote branch, + set up configuration so that git-pull will not retrieve data + from the remote branch, ignoring the branch.autosetupmerge + configuration variable. + -l:: Create the new branch's ref log. This activates recording of all changes to made the branch ref, enabling use of date @@ -56,14 +77,55 @@ OPTIONS + 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`. +and mark the resolved paths with `git add` (or `git rm` if the merge +should result in deletion of the path). :: Name for the new branch. :: Branch to checkout; may be any object ID that resolves to a - commit. Defaults to HEAD. + 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. If you did this by mistake, you can ask +the reflog for HEAD where you were, e.g. + +------------ +$ git log -g -2 HEAD +------------ EXAMPLES @@ -134,11 +196,11 @@ 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: +`git add` as usual: + ------------ $ edit frotz -$ git update-index frotz +$ git add frotz ------------