mirrors/git
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

git-worktree.txt: discuss branch-based vs. throwaway worktrees

Browse Source 
By default, `git worktree add` creates a new worktree associated with a
particular branch (which may have been created automatically if not
specified explicitly on the command-line). It is also convenient to
create throwaway worktrees not associated with any branch, which can be
handy when making experimental changes or doing testing. However, the
latter use-case may not be obvious to newcomers since the high-level
description of worktrees talks only about checking out "more than one
branch at a time". Therefore, enhance the description to to discuss both
use-cases.

A secondary goal of highlighting the distinction between branch-based
and throwaway worktrees is to help newcomers understand that the
simplest form `git worktree add <path>` automatically creates a new
branch. Stating this early in the description, may help newcomers avoid
creating branches without realizing they are doing so, and later
wondering why `git branch --list` shows branches the user did not
intentionally create.

Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Eric Sunshine
2020-09-06 20:02:22 -04:00
committed by Junio C Hamano
parent c670aa47df
commit dccadad736
1 changed files with 12 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
Documentation/git-worktree.txt
View File

@ -31,6 +31,18 @@ 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 bare repository) and zero or more linked working trees. When you are done
with a linked working tree, remove it with `git worktree remove`. with a linked working tree, 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.
If a working tree is deleted without using `git worktree remove`, then If a working tree is deleted without using `git worktree remove`, then
its associated administrative files, which reside in the repository its associated administrative files, which reside in the repository
(see "DETAILS" below), will eventually be removed automatically (see (see "DETAILS" below), will eventually be removed automatically (see