From 93a36493e2c9478c496328118dc52f6b270c7408 Mon Sep 17 00:00:00 2001 From: Eric Sunshine Date: Mon, 6 Jul 2015 13:30:40 -0400 Subject: [PATCH] Documentation: move linked worktree description from checkout to worktree Now that the git-worktree command exists, its documentation page is the natural place for the linked worktree description to reside. Relocate the "MULTIPLE WORKING TREES" description verbatim from git-checkout.txt to git-worktree.txt. Signed-off-by: Eric Sunshine Signed-off-by: Junio C Hamano --- Documentation/git-checkout.txt | 69 ++---------------------------------------- Documentation/git-worktree.txt | 62 +++++++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 67 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index ce223e69a0..77b7141f02 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -229,8 +229,8 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. 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. + specific files such as HEAD, index, etc. See + linkgit:git-worktree[1] for a description of linked worktrees. --ignore-other-worktrees:: `git checkout` refuses when the wanted ref is already checked @@ -401,71 +401,6 @@ $ git reflog -2 HEAD # or $ 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 worktree prune` 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 -------- diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 1ac1217b0f..3d288967f3 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -17,6 +17,68 @@ DESCRIPTION Manage multiple worktrees attached to the same repository. These are created by the command `git checkout --to`. +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 worktree prune` 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. + COMMANDS -------- prune:: -- 2.11.4.GIT