diff options
Diffstat (limited to 'Documentation/git-worktree.txt')
| -rw-r--r-- | Documentation/git-worktree.txt | 275 |
1 files changed, 140 insertions, 135 deletions
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 9e862fbcf7..453e155022 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -25,45 +25,49 @@ Manage multiple working trees attached to the same repository. A git repository can support multiple working trees, allowing you to check out more than one branch at a time. With `git worktree add` 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 -linkgit:git-init[1] or linkgit:git-clone[1]. -A repository has one main working tree (if it's not a -bare repository) and zero or more linked working trees. When you are done -with a linked working tree, remove it with `git worktree remove`. +tree is associated with the repository, along with additional metadata +that differentiates that working tree from others in the same repository. +The working tree, along with this metadata, is called a "worktree". + +This new worktree is called a "linked worktree" as opposed to the "main +worktree" prepared by linkgit:git-init[1] or linkgit:git-clone[1]. +A repository has one main worktree (if it's not a bare repository) and +zero or more linked worktrees. When you are done with a linked worktree, +remove it with `git worktree remove`. In its simplest form, `git worktree add <path>` automatically creates a new branch whose name is the final component of `<path>`, which is convenient if you plan to work on a new topic. For instance, `git worktree add ../hotfix` creates new branch `hotfix` and checks it out at -path `../hotfix`. To instead work on an existing branch in a new working -tree, use `git worktree add <path> <branch>`. On the other hand, if you -just plan to make some experimental changes or do testing without -disturbing existing development, it is often convenient to create a -'throwaway' working tree not associated with any branch. For instance, -`git worktree add -d <path>` creates a new working tree with a detached -`HEAD` at the same commit as the current branch. +path `../hotfix`. To instead work on an existing branch in a new worktree, +use `git worktree add <path> <branch>`. On the other hand, if you just +plan to make some experimental changes or do testing without disturbing +existing development, it is often convenient to create a 'throwaway' +worktree not associated with any branch. For instance, +`git worktree add -d <path>` creates a new worktree with a detached `HEAD` +at the same commit as the current branch. If a working tree is deleted without using `git worktree remove`, then its associated administrative files, which reside in the repository (see "DETAILS" below), will eventually be removed automatically (see `gc.worktreePruneExpire` 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 administrative files. +`git worktree prune` in the main or any linked worktree to clean up any +stale administrative files. -If a linked working tree is stored on a portable device or network share -which is not always mounted, you can prevent its administrative files from -being pruned by issuing the `git worktree lock` command, optionally -specifying `--reason` to explain why the working tree is locked. +If the working tree for a linked worktree is stored on a portable device +or network share which is not always mounted, you can prevent its +administrative files from being pruned by issuing the `git worktree lock` +command, optionally specifying `--reason` to explain why the worktree is +locked. COMMANDS -------- add <path> [<commit-ish>]:: -Create `<path>` and checkout `<commit-ish>` into it. The new working directory -is linked to the current repository, sharing everything except working -directory specific files such as `HEAD`, `index`, etc. As a convenience, -`<commit-ish>` may be a bare "`-`", which is synonymous with `@{-1}`. +Create a worktree at `<path>` and checkout `<commit-ish>` into it. The new worktree +is linked to the current repository, sharing everything except per-worktree +files such as `HEAD`, `index`, etc. As a convenience, `<commit-ish>` may +be a bare "`-`", which is synonymous with `@{-1}`. + If `<commit-ish>` is a branch name (call it `<branch>`) and is not found, and neither `-b` nor `-B` nor `--detach` are used, but there does @@ -84,100 +88,97 @@ branches from there if `<branch>` is ambiguous but exists on the linkgit:git-config[1]. + If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used, -then, as a convenience, the new working tree is associated with a branch -(call it `<branch>`) named after `$(basename <path>)`. If `<branch>` -doesn't exist, a new branch based on `HEAD` is automatically created as -if `-b <branch>` was given. If `<branch>` does exist, it will be -checked out in the new working tree, if it's not checked out anywhere -else, otherwise the command will refuse to create the working tree (unless -`--force` is used). +then, as a convenience, the new worktree is associated with a branch (call +it `<branch>`) named after `$(basename <path>)`. If `<branch>` doesn't +exist, a new branch based on `HEAD` is automatically created as if +`-b <branch>` was given. If `<branch>` does exist, it will be checked out +in the new worktree, if it's not checked out anywhere else, otherwise the +command will refuse to create the worktree (unless `--force` is used). list:: -List details of each working tree. The main working tree is listed first, -followed by each of the linked working trees. The output details include -whether the working tree is bare, the revision currently checked out, the +List details of each worktree. The main worktree is listed first, +followed by each of the linked worktrees. The output details include +whether the worktree is bare, the revision currently checked out, the branch currently checked out (or "detached HEAD" if none), "locked" if -the worktree is locked, "prunable" if the worktree can be pruned by `prune` -command. +the worktree is locked, "prunable" if the worktree can be pruned by the +`prune` command. lock:: -If a working tree is on a portable device or network share which -is not always mounted, lock it to prevent its administrative -files from being pruned automatically. This also prevents it from -being moved or deleted. Optionally, specify a reason for the lock -with `--reason`. +If a worktree is on a portable device or network share which is not always +mounted, lock it to prevent its administrative files from being pruned +automatically. This also prevents it from being moved or deleted. +Optionally, specify a reason for the lock with `--reason`. move:: -Move a working tree to a new location. Note that the main working tree -or linked working trees containing submodules cannot be moved with this -command. (The `git worktree repair` command, however, can reestablish -the connection with linked working trees if you move the main working -tree manually.) +Move a worktree to a new location. Note that the main worktree or linked +worktrees containing submodules cannot be moved with this command. (The +`git worktree repair` command, however, can reestablish the connection +with linked worktrees if you move the main worktree manually.) prune:: -Prune working tree information in `$GIT_DIR/worktrees`. +Prune worktree information in `$GIT_DIR/worktrees`. remove:: -Remove a working tree. Only clean working trees (no untracked files -and no modification in tracked files) can be removed. Unclean working -trees or ones with submodules can be removed with `--force`. The main -working tree cannot be removed. +Remove a worktree. Only clean worktrees (no untracked files and no +modification in tracked files) can be removed. Unclean worktrees or ones +with submodules can be removed with `--force`. The main worktree cannot be +removed. repair [<path>...]:: -Repair working tree administrative files, if possible, if they have -become corrupted or outdated due to external factors. +Repair worktree administrative files, if possible, if they have become +corrupted or outdated due to external factors. + -For instance, if the main working tree (or bare repository) is moved, -linked working trees will be unable to locate it. Running `repair` in -the main working tree will reestablish the connection from linked -working trees back to the main working tree. +For instance, if the main worktree (or bare repository) is moved, linked +worktrees will be unable to locate it. Running `repair` in the main +worktree will reestablish the connection from linked worktrees back to the +main worktree. + -Similarly, if a linked working tree is moved without using `git worktree -move`, the main working tree (or bare repository) will be unable to -locate it. Running `repair` within the recently-moved working tree will -reestablish the connection. If multiple linked working trees are moved, -running `repair` from any working tree with each tree's new `<path>` as -an argument, will reestablish the connection to all the specified paths. +Similarly, if the working tree for a linked worktree is moved without +using `git worktree move`, the main worktree (or bare repository) will be +unable to locate it. Running `repair` within the recently-moved worktree +will reestablish the connection. If multiple linked worktrees are moved, +running `repair` from any worktree with each tree's new `<path>` as an +argument, will reestablish the connection to all the specified paths. + -If both the main working tree and linked working trees have been moved -manually, then running `repair` in the main working tree and specifying the -new `<path>` of each linked working tree will reestablish all connections -in both directions. +If both the main worktree and linked worktrees have been moved manually, +then running `repair` in the main worktree and specifying the new `<path>` +of each linked worktree will reestablish all connections in both +directions. unlock:: -Unlock a working tree, allowing it to be pruned, moved or deleted. +Unlock a worktree, allowing it to be pruned, moved or deleted. OPTIONS ------- -f:: --force:: - By default, `add` refuses to create a new working tree when + By default, `add` refuses to create a new worktree when `<commit-ish>` is a branch name and is already checked out by - another working tree, or if `<path>` is already assigned to some - working tree but is missing (for instance, if `<path>` was deleted + another worktree, or if `<path>` is already assigned to some + worktree but is missing (for instance, if `<path>` was deleted manually). This option overrides these safeguards. To add a missing but - locked working tree path, specify `--force` twice. + locked worktree path, specify `--force` twice. + -`move` refuses to move a locked working tree unless `--force` is specified -twice. If the destination is already assigned to some other working tree but is +`move` refuses to move a locked worktree unless `--force` is specified +twice. If the destination is already assigned to some other worktree but is missing (for instance, if `<new-path>` was deleted manually), then `--force` allows the move to proceed; use `--force` twice if the destination is locked. + -`remove` refuses to remove an unclean working tree unless `--force` is used. -To remove a locked working tree, specify `--force` twice. +`remove` refuses to remove an unclean worktree unless `--force` is used. +To remove a locked worktree, specify `--force` twice. -b <new-branch>:: -B <new-branch>:: With `add`, create a new branch named `<new-branch>` starting at - `<commit-ish>`, and check out `<new-branch>` into the new working tree. + `<commit-ish>`, and check out `<new-branch>` into the new worktree. If `<commit-ish>` is omitted, it defaults to `HEAD`. By default, `-b` refuses to create a new branch if it already exists. `-B` overrides this safeguard, resetting `<new-branch>` to @@ -185,7 +186,7 @@ To remove a locked working tree, specify `--force` twice. -d:: --detach:: - With `add`, detach `HEAD` in the new working tree. See "DETACHED HEAD" + With `add`, detach `HEAD` in the new worktree. See "DETACHED HEAD" in linkgit:git-checkout[1]. --[no-]checkout:: @@ -211,7 +212,7 @@ This can also be set up as the default behaviour by using the `--track` in linkgit:git-branch[1] for details. --lock:: - Keep the working tree locked after creation. This is the + Keep the worktree locked after creation. This is the equivalent of `git worktree lock` after `git worktree add`, but without a race condition. @@ -236,43 +237,42 @@ This can also be set up as the default behaviour by using the With `list`, output additional information about worktrees (see below). --expire <time>:: - With `prune`, only expire unused working trees older than `<time>`. + With `prune`, only expire unused worktrees older than `<time>`. + -With `list`, annotate missing working trees as prunable if they are -older than `<time>`. +With `list`, annotate missing worktrees as prunable if they are older than +`<time>`. --reason <string>:: - With `lock` or with `add --lock`, an explanation why the working tree is locked. + With `lock` or with `add --lock`, an explanation why the worktree + is locked. <worktree>:: - Working trees can be identified by path, either relative or - absolute. + Worktrees can be identified by path, either relative or absolute. + -If the last path components in the working tree's path is unique among -working trees, it can be used to identify a working tree. For example if -you only have two working trees, at `/abc/def/ghi` and `/abc/def/ggg`, -then `ghi` or `def/ghi` is enough to point to the former working tree. +If the last path components in the worktree's path is unique among +worktrees, it can be used to identify a worktree. For example if you only +have two worktrees, at `/abc/def/ghi` and `/abc/def/ggg`, then `ghi` or +`def/ghi` is enough to point to the former worktree. REFS ---- -In multiple working trees, some refs may be shared between all working -trees and some refs are local. One example is `HEAD` which is different for each -working tree. This section is about the sharing rules and how to access -refs of one working tree from another. - -In general, all pseudo refs are per working tree and all refs starting -with `refs/` are shared. Pseudo refs are ones like `HEAD` which are -directly under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are -exceptions, however: refs inside `refs/bisect` and `refs/worktree` are not -shared. - -Refs that are per working tree can still be accessed from another -working tree via two special paths, `main-worktree` and `worktrees`. The -former gives access to per-working tree refs of the main working tree, -while the latter to all linked working trees. +When using multiple worktrees, some refs are shared between all worktrees, +but others are specific to an individual worktree. One example is `HEAD`, +which is different for each worktree. This section is about the sharing +rules and how to access refs of one worktree from another. + +In general, all pseudo refs are per-worktree and all refs starting with +`refs/` are shared. Pseudo refs are ones like `HEAD` which are directly +under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are exceptions, +however: refs inside `refs/bisect` and `refs/worktree` are not shared. + +Refs that are per-worktree can still be accessed from another worktree via +two special paths, `main-worktree` and `worktrees`. The former gives +access to per-worktree refs of the main worktree, while the latter to all +linked worktrees. For example, `main-worktree/HEAD` or `main-worktree/refs/bisect/good` -resolve to the same value as the main working tree's `HEAD` and +resolve to the same value as the main worktree's `HEAD` and `refs/bisect/good` respectively. Similarly, `worktrees/foo/HEAD` or `worktrees/bar/refs/bisect/bad` are the same as `$GIT_COMMON_DIR/worktrees/foo/HEAD` and @@ -284,13 +284,13 @@ which will handle refs correctly. CONFIGURATION FILE ------------------ -By default, the repository `config` file is shared across all working -trees. If the config variables `core.bare` or `core.worktree` are -already present in the config file, they will be applied to the main -working trees only. +By default, the repository `config` file is shared across all worktrees. +If the config variables `core.bare` or `core.worktree` are present in the +common config file and `extensions.worktreeConfig` is disabled, then they +will be applied to the main worktree only. -In order to have configuration specific to working trees, you can turn -on the `worktreeConfig` extension, e.g.: +In order to have worktree-specific configuration, you can turn on the +`worktreeConfig` extension, e.g.: ------------ $ git config extensions.worktreeConfig true @@ -303,40 +303,45 @@ versions will refuse to access repositories with this extension. Note that in this file, the exception for `core.bare` and `core.worktree` is gone. If they exist in `$GIT_DIR/config`, you must move -them to the `config.worktree` of the main working tree. You may also -take this opportunity to review and move other configuration that you -do not want to share to all working trees: +them to the `config.worktree` of the main worktree. You may also take this +opportunity to review and move other configuration that you do not want to +share to all worktrees: + + - `core.worktree` should never be shared. + + - `core.bare` should not be shared if the value is `core.bare=true`. - - `core.worktree` and `core.bare` should never be shared + - `core.sparseCheckout` should not be shared, unless you are sure you + always use sparse checkout for all worktrees. - - `core.sparseCheckout` is recommended per working tree, unless you - are sure you always use sparse checkout for all working trees. +See the documentation of `extensions.worktreeConfig` in +linkgit:git-config[1] for more details. DETAILS ------- -Each linked working tree has a private sub-directory in the repository's +Each linked worktree 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 +the base name of the linked worktree's path, possibly appended with a number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the command `git worktree add /path/other/test-next next` creates the linked -working tree in `/path/other/test-next` and also creates a +worktree 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 +Within a linked worktree, `$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` +`$GIT_COMMON_DIR` is set to point back to the main worktree'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. +the top directory of the linked worktree. 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 +linked worktree `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, except `refs/bisect` and +since refs are shared across all worktrees, except `refs/bisect` and `refs/worktree`. See linkgit:gitrepository-layout[5] for more information. The rule of @@ -344,8 +349,8 @@ 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. -If you manually move a linked working tree, you need to update the `gitdir` file -in the entry's directory. For example, if a linked working tree is moved +If you manually move a linked worktree, you need to update the `gitdir` file +in the entry's directory. For example, if a linked worktree is moved to `/newpath/test-next` and its `.git` file points to `/path/main/.git/worktrees/test-next`, then update `/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next` @@ -354,10 +359,10 @@ automatically. To prevent a `$GIT_DIR/worktrees` entry from being pruned (which can be useful in some situations, such as when the -entry's working tree is stored on a portable device), use the +entry's worktree is stored on a portable device), use the `git worktree lock` command, which adds 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 +plain text. For example, if a linked worktree'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 @@ -378,11 +383,11 @@ $ git worktree list /path/to/other-linked-worktree 1234abc (detached HEAD) ------------ -The command also shows annotations for each working tree, according to its state. +The command also shows annotations for each worktree, according to its state. These annotations are: - * `locked`, if the working tree is locked. - * `prunable`, if the working tree can be pruned via `git worktree prune`. + * `locked`, if the worktree is locked. + * `prunable`, if the worktree can be pruned via `git worktree prune`. ------------ $ git worktree list @@ -400,14 +405,14 @@ $ git worktree list --verbose /path/to/linked-worktree abcd1234 [master] /path/to/locked-worktree-no-reason abcd5678 (detached HEAD) locked /path/to/locked-worktree-with-reason 1234abcd (brancha) - locked: working tree path is mounted on a portable device + locked: worktree path is mounted on a portable device /path/to/prunable-worktree 5678abc1 (detached HEAD) prunable: gitdir file points to non-existent location ------------ Note that the annotation is moved to the next line if the additional information is available, otherwise it stays on the same line as the -working tree itself. +worktree itself. Porcelain Format ~~~~~~~~~~~~~~~~ @@ -416,7 +421,7 @@ label and value separated by a single space. Boolean attributes (like `bare` and `detached`) are listed as a label only, and are present only if the value is true. Some attributes (like `locked`) can be listed as a label only or with a value depending upon whether a reason is available. The first -attribute of a working tree is always `worktree`, an empty line indicates the +attribute of a worktree is always `worktree`, an empty line indicates the end of the record. For example: ------------ @@ -468,7 +473,7 @@ demands that you fix something immediately. You might typically use linkgit:git-stash[1] to store your changes away temporarily, however, your working tree is in such a state of disarray (with new, moved, and removed files, and other bits and pieces strewn around) that you don't want to risk -disturbing any of it. Instead, you create a temporary linked working tree to +disturbing any of it. Instead, you create a temporary linked worktree to make the emergency fix, remove it when done, and then resume your earlier refactoring session. |