@matheusbsbs / matheus-bagliano / commits / beebc6df4c

Documentation/git-submodule: cleanup "add" section

The "add" section for 'git-submodule' is redundant in its description and the short synopsis line. Fix it. Remove the redundant mentioning of the 'repository' argument being mandatory. The text is hard to read because of back-references, so remove those. Replace the word "humanish" by "canonical" as that conveys better what we do to guess the path. While at it, quote all occurrences of '.gitmodules' as that is an important file in the submodule context, also link to it on its first mention. Helped-by: Stefan Beller <sbeller@google.com> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> Reviewed-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Kaartic Sivaraam committed Jun 22, 2017 at 02:51 UTC beebc6df4c0db886a5bf8c3eb5bf92726e944851

1 file changed +21 -28

Documentation/git-submodule.txt

+21 -28

@@ -63,14 +63,6 @@ add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--dep

63 to the changeset to be committed next to the current

64 project: the current project is termed the "superproject".

65 +

66 -This requires at least one argument: <repository>. The optional

67 -argument <path> is the relative location for the cloned submodule

68 -to exist in the superproject. If <path> is not given, the

69 -"humanish" part of the source repository is used ("repo" for

70 -"/path/to/repo.git" and "foo" for "host.xz:foo/.git").

71 -The <path> is also used as the submodule's logical name in its

72 -configuration entries unless `--name` is used to specify a logical name.

73 -+

66 <repository> is the URL of the new submodule's origin repository.

67 This may be either an absolute URL, or (if it begins with ./

68 or ../), the location relative to the superproject's default remote

@@ -87,21 +79,22 @@ If the superproject doesn't have a default remote configured

79 the superproject is its own authoritative upstream and the current

80 working directory is used instead.

81 +

90 -<path> is the relative location for the cloned submodule to

91 -exist in the superproject. If <path> does not exist, then the

92 -submodule is created by cloning from the named URL. If <path> does

93 -exist and is already a valid Git repository, then this is added

94 -to the changeset without cloning. This second form is provided

95 -to ease creating a new submodule from scratch, and presumes

96 -the user will later push the submodule to the given URL.

82 +The optional argument <path> is the relative location for the cloned

83 +submodule to exist in the superproject. If <path> is not given, the

84 +canonical part of the source repository is used ("repo" for

85 +"/path/to/repo.git" and "foo" for "host.xz:foo/.git"). If <path>

86 +exists and is already a valid Git repository, then it is staged

87 +for commit without cloning. The <path> is also used as the submodule's

88 +logical name in its configuration entries unless `--name` is used

89 +to specify a logical name.

90 +

98 -In either case, the given URL is recorded into .gitmodules for

99 -use by subsequent users cloning the superproject. If the URL is

100 -given relative to the superproject's repository, the presumption

101 -is the superproject and submodule repositories will be kept

102 -together in the same relative location, and only the

103 -superproject's URL needs to be provided: git-submodule will correctly

104 -locate the submodule using the relative URL in .gitmodules.

91 +The given URL is recorded into `.gitmodules` for use by subsequent users

92 +cloning the superproject. If the URL is given relative to the

93 +superproject's repository, the presumption is the superproject and

94 +submodule repositories will be kept together in the same relative

95 +location, and only the superproject's URL needs to be provided.

96 +git-submodule will correctly locate the submodule using the relative

97 +URL in `.gitmodules`.

99 status [--cached] [--recursive] [--] [<path>...]::

100 Show the status of the submodules. This will print the SHA-1 of the

@@ -123,7 +116,7 @@ too (and can also report changes to a submodule's work tree).

116 init [--] [<path>...]::

117 Initialize the submodules recorded in the index (which were

118 added and committed elsewhere) by setting `submodule.$name.url`

126 - in .git/config. It uses the same setting from .gitmodules as

119 + in .git/config. It uses the same setting from `.gitmodules` as

120 a template. If the URL is relative, it will be resolved using

121 the default remote. If there is no default remote, the current

122 repository will be assumed to be upstream.

@@ -197,7 +190,7 @@ configuration variable:

190 none;; the submodule is not updated.

191

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

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

193 +setting as stored in `.gitmodules`, you can automatically initialize the

194 submodule with the `--init` option.

195

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

@@ -220,7 +213,7 @@ foreach [--recursive] <command>::

213 Evaluates an arbitrary shell command in each checked out submodule.

214 The command has access to the variables $name, $path, $sha1 and

215 $toplevel:

223 - $name is the name of the relevant submodule section in .gitmodules,

216 + $name is the name of the relevant submodule section in `.gitmodules`,

217 $path is the name of the submodule directory relative to the

218 superproject, $sha1 is the commit as recorded in the superproject,

219 and $toplevel is the absolute path to the top-level of the superproject.

@@ -242,7 +235,7 @@ git submodule foreach 'echo $path `git rev-parse HEAD`'

235

236 sync [--recursive] [--] [<path>...]::

237 Synchronizes submodules' remote URL configuration setting

245 - to the value specified in .gitmodules. It will only affect those

238 + to the value specified in `.gitmodules`. It will only affect those

239 submodules which already have a URL entry in .git/config (that is the

240 case when they are initialized or freshly added). This is useful when

241 submodule URLs change upstream and you need to update your local

@@ -413,7 +406,7 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.

406 --[no-]recommend-shallow::

407 This option is only valid for the update command.

408 The initial clone of a submodule will use the recommended

416 - `submodule.<name>.shallow` as provided by the .gitmodules file

409 + `submodule.<name>.shallow` as provided by the `.gitmodules` file

410 by default. To ignore the suggestions use `--no-recommend-shallow`.

411

412 -j <n>::

@@ -429,7 +422,7 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.

422

423 FILES

424 -----

432 -When initializing submodules, a .gitmodules file in the top-level directory

425 +When initializing submodules, a `.gitmodules` file in the top-level directory

426 of the containing repository is used to find the url of each submodule.

427 This file should be formatted in the same way as `$GIT_DIR/config`. The key

428 to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5]