From: Junio C Hamano Date: Fri, 10 Jul 2015 21:17:54 +0000 (-0700) Subject: Merge branch 'tb/checkout-doc' X-Git-Tag: v2.5.0-rc2~20 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/e12fc40a154d6bd227de0596d9c0f33bb582d868?ds=sidebyside;hp=-c Merge branch 'tb/checkout-doc' Doc update. * tb/checkout-doc: git-checkout.txt: document "git checkout " better --- e12fc40a154d6bd227de0596d9c0f33bb582d868 diff --combined Documentation/git-checkout.txt index d263a5652f,7540e026f5..2df6d0d4b4 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@@ -3,7 -3,7 +3,7 @@@ git-checkout(1 NAME ---- - git-checkout - Checkout a branch or paths to the working tree + git-checkout - Switch branches or restore working tree files SYNOPSIS -------- @@@ -89,6 -89,10 +89,10 @@@ Omitting detaches HEAD at the (i.e. commit, tag or tree) to update the index for the given paths before updating the working tree. + + 'git checkout' with or `--patch` is used to restore modified or + deleted paths to their original contents from the index or replace paths + with the contents from a named (most often a commit-ish). + + The index may contain unmerged entries because of a previous 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. @@@ -225,19 -229,6 +229,19 @@@ This means that you can use `git checko edits from your current working tree. See the ``Interactive Mode'' section of linkgit:git-add[1] to learn how to operate the `--patch` mode. +--to=:: + Check out a branch in a separate working directory at + ``. A new working directory is linked to the current + repository, sharing everything except working directory + specific files such as HEAD, index... See "MULTIPLE WORKING + TREES" section for more information. + +--ignore-other-worktrees:: + `git checkout` refuses when the wanted ref is already checked + out by another worktree. This option makes it check the ref + out anyway. In other words, the ref can be held by more than one + worktree. + :: 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 @@@ -401,71 -392,6 +405,71 @@@ $ git reflog -2 HEAD # o $ git log -g -2 HEAD ------------ +MULTIPLE WORKING TREES +---------------------- + +A git repository can support multiple working trees, allowing you to check +out more than one branch at a time. With `git checkout --to` a new working +tree is associated with the repository. This new working tree is called a +"linked working tree" as opposed to the "main working tree" prepared by "git +init" or "git clone". A repository has one main working tree (if it's not a +bare repository) and zero or more linked working trees. + +Each linked working tree has a private sub-directory in the repository's +$GIT_DIR/worktrees directory. The private sub-directory's name is usually +the base name of the linked working tree's path, possibly appended with a +number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the +command `git checkout --to /path/other/test-next next` creates the linked +working tree in `/path/other/test-next` and also creates a +`$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1` +if `test-next` is already taken). + +Within a linked working tree, $GIT_DIR is set to point to this private +directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and +$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR +(e.g. `/path/main/.git`). These settings are made in a `.git` file located at +the top directory of the linked working tree. + +Path resolution via `git rev-parse --git-path` uses either +$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the +linked working tree `git rev-parse --git-path HEAD` returns +`/path/main/.git/worktrees/test-next/HEAD` (not +`/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git +rev-parse --git-path refs/heads/master` uses +$GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`, +since refs are shared across all working trees. + +See linkgit:gitrepository-layout[5] for more information. The rule of +thumb is do not make any assumption about whether a path belongs to +$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something +inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. + +When you are done with a linked working tree you can simply delete it. +The working tree's entry in the repository's $GIT_DIR/worktrees +directory will eventually be removed automatically (see +`gc.pruneworktreesexpire` in linkgit::git-config[1]), or you can run +`git prune --worktrees` in the main or any linked working tree to +clean up any stale entries in $GIT_DIR/worktrees. + +If you move a linked working directory to another file system, or +within a file system that does not support hard links, you need to run +at least one git command inside the linked working directory +(e.g. `git status`) in order to update its entry in $GIT_DIR/worktrees +so that it does not get automatically removed. + +To prevent a $GIT_DIR/worktrees entry from from being pruned (which +can be useful in some situations, such as when the +entry's working tree is stored on a portable device), add a file named +'locked' to the entry's directory. The file contains the reason in +plain text. For example, if a linked working tree's `.git` file points +to `/path/main/.git/worktrees/test-next` then a file named +`/path/main/.git/worktrees/test-next/locked` will prevent the +`test-next` entry from being pruned. See +linkgit:gitrepository-layout[5] for details. + +Multiple checkout support for submodules is incomplete. It is NOT +recommended to make multiple checkouts of a superproject. + EXAMPLES --------