@matheusbsbs / matheus-bagliano / commits / 599701441e

worktree: use 'worktree' over 'working tree'

It is helpful to distinguish between a 'working tree' and a 'worktree'. A worktree contains a working tree plus additional metadata. This metadata includes per-worktree refs and worktree-specific config. This is the second of multiple changes to git-worktree.txt, restricted to the COMMANDS section. There is some language around the movement of "the working tree of a linked worktree" which is used once, but the remaining uses are left as just moving "a linked worktree" for brevity. Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Derrick Stolee <derrickstolee@github.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Derrick Stolee committed Feb 23, 2022 at 14:29 UTC 599701441e5e7853339306f56e82cb02543d53a7

1 file changed +41 -44

Documentation/git-worktree.txt

+41 -44

@@ -88,75 +88,72 @@ branches from there if `<branch>` is ambiguous but exists on the

88 linkgit:git-config[1].

89 +

90 If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used,

91 -then, as a convenience, the new working tree is associated with a branch

92 -(call it `<branch>`) named after `$(basename <path>)`. If `<branch>`

93 -doesn't exist, a new branch based on `HEAD` is automatically created as

94 -if `-b <branch>` was given. If `<branch>` does exist, it will be

95 -checked out in the new working tree, if it's not checked out anywhere

96 -else, otherwise the command will refuse to create the working tree (unless

97 -`--force` is used).

91 +then, as a convenience, the new worktree is associated with a branch (call

92 +it `<branch>`) named after `$(basename <path>)`. If `<branch>` doesn't

93 +exist, a new branch based on `HEAD` is automatically created as if

94 +`-b <branch>` was given. If `<branch>` does exist, it will be checked out

95 +in the new worktree, if it's not checked out anywhere else, otherwise the

96 +command will refuse to create the worktree (unless `--force` is used).

98 list::

101 -List details of each working tree. The main working tree is listed first,

102 -followed by each of the linked working trees. The output details include

103 -whether the working tree is bare, the revision currently checked out, the

100 +List details of each worktree. The main worktree is listed first,

101 +followed by each of the linked worktrees. The output details include

102 +whether the worktree is bare, the revision currently checked out, the

103 branch currently checked out (or "detached HEAD" if none), "locked" if

105 -the worktree is locked, "prunable" if the worktree can be pruned by `prune`

106 -command.

104 +the worktree is locked, "prunable" if the worktree can be pruned by the

105 +`prune` command.

106

107 lock::

108

110 -If a working tree is on a portable device or network share which

111 -is not always mounted, lock it to prevent its administrative

112 -files from being pruned automatically. This also prevents it from

113 -being moved or deleted. Optionally, specify a reason for the lock

114 -with `--reason`.

109 +If a worktree is on a portable device or network share which is not always

110 +mounted, lock it to prevent its administrative files from being pruned

111 +automatically. This also prevents it from being moved or deleted.

112 +Optionally, specify a reason for the lock with `--reason`.

113

114 move::

115

118 -Move a working tree to a new location. Note that the main working tree

119 -or linked working trees containing submodules cannot be moved with this

120 -command. (The `git worktree repair` command, however, can reestablish

121 -the connection with linked working trees if you move the main working

122 -tree manually.)

116 +Move a worktree to a new location. Note that the main worktree or linked

117 +worktrees containing submodules cannot be moved with this command. (The

118 +`git worktree repair` command, however, can reestablish the connection

119 +with linked worktrees if you move the main worktree manually.)

120

121 prune::

122

126 -Prune working tree information in `$GIT_DIR/worktrees`.

123 +Prune worktree information in `$GIT_DIR/worktrees`.

124

125 remove::

126

130 -Remove a working tree. Only clean working trees (no untracked files

131 -and no modification in tracked files) can be removed. Unclean working

132 -trees or ones with submodules can be removed with `--force`. The main

133 -working tree cannot be removed.

127 +Remove a worktree. Only clean worktrees (no untracked files and no

128 +modification in tracked files) can be removed. Unclean worktrees or ones

129 +with submodules can be removed with `--force`. The main worktree cannot be

130 +removed.

131

132 repair [<path>...]::

133

137 -Repair working tree administrative files, if possible, if they have

138 -become corrupted or outdated due to external factors.

134 +Repair worktree administrative files, if possible, if they have become

135 +corrupted or outdated due to external factors.

136 +

140 -For instance, if the main working tree (or bare repository) is moved,

141 -linked working trees will be unable to locate it. Running `repair` in

142 -the main working tree will reestablish the connection from linked

143 -working trees back to the main working tree.

137 +For instance, if the main worktree (or bare repository) is moved, linked

138 +worktrees will be unable to locate it. Running `repair` in the main

139 +worktree will reestablish the connection from linked worktrees back to the

140 +main worktree.

141 +

145 -Similarly, if a linked working tree is moved without using `git worktree

146 -move`, the main working tree (or bare repository) will be unable to

147 -locate it. Running `repair` within the recently-moved working tree will

148 -reestablish the connection. If multiple linked working trees are moved,

149 -running `repair` from any working tree with each tree's new `<path>` as

150 -an argument, will reestablish the connection to all the specified paths.

142 +Similarly, if the working tree for a linked worktree is moved without

143 +using `git worktree move`, the main worktree (or bare repository) will be

144 +unable to locate it. Running `repair` within the recently-moved worktree

145 +will reestablish the connection. If multiple linked worktrees are moved,

146 +running `repair` from any worktree with each tree's new `<path>` as an

147 +argument, will reestablish the connection to all the specified paths.

148 +

152 -If both the main working tree and linked working trees have been moved

153 -manually, then running `repair` in the main working tree and specifying the

154 -new `<path>` of each linked working tree will reestablish all connections

155 -in both directions.

149 +If both the main worktree and linked worktrees have been moved manually,

150 +then running `repair` in the main worktree and specifying the new `<path>`

151 +of each linked worktree will reestablish all connections in both

152 +directions.

153

154 unlock::

155

159 -Unlock a working tree, allowing it to be pruned, moved or deleted.

156 +Unlock a worktree, allowing it to be pruned, moved or deleted.

157

158 OPTIONS

159 -------