@matheusbsbs / matheus-bagliano / commits / 5c31acfbe2

submodule: improve documentation of update subcommand

The documentation of 'git submodule update' has several problems: 1) It mentions that value 'none' of submodule.$name.update can be overridden by --checkout, but other combinations of configuration values and command line options are not mentioned. 2) The documentation of submodule.$name.update is scattered across three places, which is confusing. 3) The documentation of submodule.$name.update in gitmodules.txt is incorrect, because the code always uses the value from .git/config and never from .gitmodules. 4) Documentation of --force was incomplete, because it is only effective in case of checkout method of update. Fix all these problems by documenting submodule.*.update in git-submodule.txt and make everybody else refer to it. Helped-by: Junio C Hamano <gitster@pobox.com> Helped-by: Jens Lehmann <Jens.Lehmann@web.de> Signed-off-by: Michal Sojka <sojkam1@fel.cvut.cz> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Michal Sojka committed Mar 2, 2015 at 23:57 UTC 5c31acfbe22cebdf1a04723b58cdb358e377632a

3 files changed +64 -37

Documentation/config.txt

+9 -5

@@ -2303,12 +2303,16 @@ status.submodulesummary::

2303

2304 submodule.<name>.path::

2305 submodule.<name>.url::

2306 + The path within this project and URL for a submodule. These

2307 + variables are initially populated by 'git submodule init'. See

2308 + linkgit:git-submodule[1] and linkgit:gitmodules[5] for

2309 + details.

2310 +

2311 submodule.<name>.update::

2307 - The path within this project, URL, and the updating strategy

2308 - for a submodule. These variables are initially populated

2309 - by 'git submodule init'; edit them to override the

2310 - URL and other values found in the `.gitmodules` file. See

2311 - linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.

2312 + The default update procedure for a submodule. This variable

2313 + is populated by `git submodule init` from the

2314 + linkgit:gitmodules[5] file. See description of 'update'

2315 + command in linkgit:git-submodule[1].

2316

2317 submodule.<name>.branch::

2318 The remote branch name for a submodule, used by `git submodule

Documentation/git-submodule.txt

+46 -20

@@ -154,27 +154,51 @@ If `--force` is specified, the submodule's work tree will be removed even if

154 it contains local modifications.

155

156 update::

157 - Update the registered submodules, i.e. clone missing submodules and

158 - checkout the commit specified in the index of the containing repository.

159 - This will make the submodules HEAD be detached unless `--rebase` or

160 - `--merge` is specified or the key `submodule.$name.update` is set to

161 - `rebase`, `merge` or `none`. `none` can be overridden by specifying

162 - `--checkout`. Setting the key `submodule.$name.update` to `!command`

163 - will cause `command` to be run. `command` can be any arbitrary shell

164 - command that takes a single argument, namely the sha1 to update to.

157 +

158 +--

159 +Update the registered submodules to match what the superproject

160 +expects by cloning missing submodules and updating the working tree of

161 +the submodules. The "updating" can be done in several ways depending

162 +on command line options and the value of `submodule.<name>.update`

163 +configuration variable. Supported update procedures are:

164 +

165 + checkout;; the commit recorded in the superproject will be

166 + checked out in the submodule on a detached HEAD. This is

167 + done when `--checkout` option is given, or no option is

168 + given, and `submodule.<name>.update` is unset, or if it is

169 + set to 'checkout'.

170 ++

171 +If `--force` is specified, the submodule will be checked out (using

172 +`git checkout --force` if appropriate), even if the commit specified

173 +in the index of the containing repository already matches the commit

174 +checked out in the submodule.

175 +

176 + rebase;; the current branch of the submodule will be rebased

177 + onto the commit recorded in the superproject. This is done

178 + when `--rebase` option is given, or no option is given, and

179 + `submodule.<name>.update` is set to 'rebase'.

180 +

181 + merge;; the commit recorded in the superproject will be merged

182 + into the current branch in the submodule. This is done

183 + when `--merge` option is given, or no option is given, and

184 + `submodule.<name>.update` is set to 'merge'.

185 +

186 + custom command;; arbitrary shell command that takes a single

187 + argument (the sha1 of the commit recorded in the

188 + superproject) is executed. This is done when no option is

189 + given, and `submodule.<name>.update` has the form of

190 + '!command'.

191 +

192 +When no option is given and `submodule.<name>.update` is set to 'none',

193 +the submodule is not updated.

194 +

195 If the submodule is not yet initialized, and you just want to use the

196 setting as stored in .gitmodules, you can automatically initialize the

197 submodule with the `--init` option.

169 -+

198 +

199 If `--recursive` is specified, this command will recurse into the

200 registered submodules, and update any nested submodules within.

172 -+

173 -If `--force` is specified, the submodule will be checked out (using

174 -`git checkout --force` if appropriate), even if the commit specified in the

175 -index of the containing repository already matches the commit checked out in

176 -the submodule.

177 -

201 +--

202 summary::

203 Show commit summary between the given commit (defaults to HEAD) and

204 working tree/index. For a submodule in question, a series of commits

@@ -238,10 +262,12 @@ OPTIONS

262 When running add, allow adding an otherwise ignored submodule path.

263 When running deinit the submodule work trees will be removed even if

264 they contain local changes.

241 - When running update, throw away local changes in submodules when

242 - switching to a different commit; and always run a checkout operation

243 - in the submodule, even if the commit listed in the index of the

244 - containing repository matches the commit checked out in the submodule.

265 + When running update (only effective with the checkout procedure),

266 + throw away local changes in submodules when switching to a

267 + different commit; and always run a checkout operation in the

268 + submodule, even if the commit listed in the index of the

269 + containing repository matches the commit checked out in the

270 + submodule.

271

272 --cached::

273 This option is only valid for status and summary commands. These

@@ -302,7 +328,7 @@ the submodule itself.

328 Checkout the commit recorded in the superproject on a detached HEAD

329 in the submodule. This is the default behavior, the main use of

330 this option is to override `submodule.$name.update` when set to

305 - `merge`, `rebase` or `none`.

331 + a value other than `checkout`.

332 If the key `submodule.$name.update` is either not explicitly set or

333 set to `checkout`, this option is implicit.

334

Documentation/gitmodules.txt

+9 -12

@@ -38,18 +38,15 @@ submodule.<name>.url::

38 In addition, there are a number of optional keys:

40 submodule.<name>.update::

41 - Defines what to do when the submodule is updated by the superproject.

42 - If 'checkout' (the default), the new commit specified in the

43 - superproject will be checked out in the submodule on a detached HEAD.

44 - If 'rebase', the current branch of the submodule will be rebased onto

45 - the commit specified in the superproject. If 'merge', the commit

46 - specified in the superproject will be merged into the current branch

47 - in the submodule.

48 - If 'none', the submodule with name `$name` will not be updated

49 - by default.

50 -

51 - This config option is overridden if 'git submodule update' is given

52 - the '--merge', '--rebase' or '--checkout' options.

41 + Defines the default update procedure for the named submodule,

42 + i.e. how the submodule is updated by "git submodule update"

43 + command in the superproject. This is only used by `git

44 + submodule init` to initialize the configuration variable of

45 + the same name. Allowed values here are 'checkout', 'rebase',

46 + 'merge' or 'none'. See description of 'update' command in

47 + linkgit:git-submodule[1] for their meaning. Note that the

48 + '!command' form is intentionally ignored here for security

49 + reasons.

51 submodule.<name>.branch::

52 A remote branch name for tracking updates in the upstream submodule.