doc: convert git-submodule to synopsis style
* convert commands to synopsis style * use _<placeholder>_ for arguments * convert inline lists into proper definition lists * minor formatting fixes Reviewed-by: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>maint
Jean-Noël Avila
Junio C Hamano
parent
83a69f1935
commit
777f5d089c
|
|
@ -8,19 +8,19 @@ git-submodule - Initialize, update or inspect submodules
|
|||
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
'git submodule' [--quiet] [--cached]
|
||||
'git submodule' [--quiet] add [<options>] [--] <repository> [<path>]
|
||||
'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
|
||||
'git submodule' [--quiet] init [--] [<path>...]
|
||||
'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...)
|
||||
'git submodule' [--quiet] update [<options>] [--] [<path>...]
|
||||
'git submodule' [--quiet] set-branch [<options>] [--] <path>
|
||||
'git submodule' [--quiet] set-url [--] <path> <newurl>
|
||||
'git submodule' [--quiet] summary [<options>] [--] [<path>...]
|
||||
'git submodule' [--quiet] foreach [--recursive] <command>
|
||||
'git submodule' [--quiet] sync [--recursive] [--] [<path>...]
|
||||
'git submodule' [--quiet] absorbgitdirs [--] [<path>...]
|
||||
[synopsis]
|
||||
git submodule [--quiet] [--cached]
|
||||
git submodule [--quiet] add [<options>] [--] <repository> [<path>]
|
||||
git submodule [--quiet] status [--cached] [--recursive] [--] [<path>...]
|
||||
git submodule [--quiet] init [--] [<path>...]
|
||||
git submodule [--quiet] deinit [-f|--force] (--all|[--] <path>...)
|
||||
git submodule [--quiet] update [<options>] [--] [<path>...]
|
||||
git submodule [--quiet] set-branch [<options>] [--] <path>
|
||||
git submodule [--quiet] set-url [--] <path> <newurl>
|
||||
git submodule [--quiet] summary [<options>] [--] [<path>...]
|
||||
git submodule [--quiet] foreach [--recursive] <command>
|
||||
git submodule [--quiet] sync [--recursive] [--] [<path>...]
|
||||
git submodule [--quiet] absorbgitdirs [--] [<path>...]
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
|
|
@ -34,34 +34,34 @@ COMMANDS
|
|||
With no arguments, shows the status of existing submodules. Several
|
||||
subcommands are available to perform operations on the submodules.
|
||||
|
||||
add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]::
|
||||
`add [-b <branch>] [-f | --force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]`::
|
||||
Add the given repository as a submodule at the given path
|
||||
to the changeset to be committed next to the current
|
||||
project: the current project is termed the "superproject".
|
||||
+
|
||||
<repository> is the URL of the new submodule's origin repository.
|
||||
This may be either an absolute URL, or (if it begins with ./
|
||||
or ../), the location relative to the superproject's default remote
|
||||
repository (Please note that to specify a repository 'foo.git'
|
||||
which is located right next to a superproject 'bar.git', you'll
|
||||
_<repository>_ is the URL of the new submodule's `origin` repository.
|
||||
This may be either an absolute URL, or (if it begins with `./`
|
||||
or `../`), the location relative to the superproject's default remote
|
||||
repository (Please note that to specify a repository `foo.git`
|
||||
which is located right next to a superproject `bar.git`, you'll
|
||||
have to use `../foo.git` instead of `./foo.git` - as one might expect
|
||||
when following the rules for relative URLs - because the evaluation
|
||||
of relative URLs in Git is identical to that of relative directories).
|
||||
+
|
||||
The default remote is the remote of the remote-tracking branch
|
||||
of the current branch. If no such remote-tracking branch exists or
|
||||
the HEAD is detached, "origin" is assumed to be the default remote.
|
||||
the `HEAD` is detached, `origin` is assumed to be the default remote.
|
||||
If the superproject doesn't have a default remote configured
|
||||
the superproject is its own authoritative upstream and the current
|
||||
working directory is used instead.
|
||||
+
|
||||
The optional argument <path> is the relative location for the cloned
|
||||
submodule to exist in the superproject. If <path> is not given, the
|
||||
canonical part of the source repository is used ("repo" for
|
||||
"/path/to/repo.git" and "foo" for "host.xz:foo/.git"). If <path>
|
||||
The optional argument _<path>_ is the relative location for the cloned
|
||||
submodule to exist in the superproject. If _<path>_ is not given, the
|
||||
canonical part of the source repository is used (`repo` for
|
||||
`/path/to/repo.git` and `foo` for `host.xz:foo/.git`). If _<path>_
|
||||
exists and is already a valid Git repository, then it is staged
|
||||
for commit without cloning. The <path> is also used as the submodule's
|
||||
logical name in its configuration entries unless `--name` is used
|
||||
for commit without cloning. The _<path>_ is also used as the submodule's
|
||||
logical name in its configuration entries unless `--name <name>` is used
|
||||
to specify a logical name.
|
||||
+
|
||||
The given URL is recorded into `.gitmodules` for use by subsequent users
|
||||
|
|
@ -75,10 +75,10 @@ URL in `.gitmodules`.
|
|||
If `--ref-format <format>` is specified, the ref storage format of newly
|
||||
cloned submodules will be set accordingly.
|
||||
|
||||
status [--cached] [--recursive] [--] [<path>...]::
|
||||
`status [--cached] [--recursive] [--] [<path>...]`::
|
||||
Show the status of the submodules. This will print the SHA-1 of the
|
||||
currently checked out commit for each submodule, along with the
|
||||
submodule path and the output of 'git describe' for the
|
||||
submodule path and the output of linkgit:git-describe[1] for the
|
||||
SHA-1. Each SHA-1 will possibly be prefixed with `-` if the submodule is
|
||||
not initialized, `+` if the currently checked out submodule commit
|
||||
does not match the SHA-1 found in the index of the containing
|
||||
|
|
@ -91,11 +91,11 @@ If `--recursive` is specified, this command will recurse into nested
|
|||
submodules, and show their status as well.
|
||||
+
|
||||
If you are only interested in changes of the currently initialized
|
||||
submodules with respect to the commit recorded in the index or the HEAD,
|
||||
submodules with respect to the commit recorded in the index or the `HEAD`,
|
||||
linkgit:git-status[1] and linkgit:git-diff[1] will provide that information
|
||||
too (and can also report changes to a submodule's work tree).
|
||||
|
||||
init [--] [<path>...]::
|
||||
`init [--] [<path>...]`::
|
||||
Initialize the submodules recorded in the index (which were
|
||||
added and committed elsewhere) by setting `submodule.$name.url`
|
||||
in `.git/config`, using the same setting from `.gitmodules` as
|
||||
|
|
@ -103,7 +103,7 @@ init [--] [<path>...]::
|
|||
the default remote. If there is no default remote, the current
|
||||
repository will be assumed to be upstream.
|
||||
+
|
||||
Optional <path> arguments limit which submodules will be initialized.
|
||||
Optional _<path>_ arguments limit which submodules will be initialized.
|
||||
If no path is specified and submodule.active has been configured, submodules
|
||||
configured to be active will be initialized, otherwise all submodules are
|
||||
initialized.
|
||||
|
|
@ -116,12 +116,12 @@ that is set to a custom command is *not* copied for security reasons.
|
|||
You can then customize the submodule clone URLs in `.git/config`
|
||||
for your local setup and proceed to `git submodule update`;
|
||||
you can also just use `git submodule update --init` without
|
||||
the explicit 'init' step if you do not intend to customize
|
||||
the explicit `init` step if you do not intend to customize
|
||||
any submodule locations.
|
||||
+
|
||||
See the add subcommand for the definition of default remote.
|
||||
|
||||
deinit [-f|--force] (--all|[--] <path>...)::
|
||||
`deinit [-f | --force] (--all|[--] <path>...)`::
|
||||
Unregister the given submodules, i.e. remove the whole
|
||||
`submodule.$name` section from .git/config together with their work
|
||||
tree. Further calls to `git submodule update`, `git submodule foreach`
|
||||
|
|
@ -139,7 +139,7 @@ If you really want to remove a submodule from the repository and commit
|
|||
that use linkgit:git-rm[1] instead. See linkgit:gitsubmodules[7] for removal
|
||||
options.
|
||||
|
||||
update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>...]::
|
||||
`update [--init] [--remote] [-N | --no-fetch] [--[no-]recommend-shallow] [-f | --force] [--checkout | --rebase | --merge] [--reference=<repository>] [--ref-format=<format>] [--depth=<depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter=<filter-spec>] [--] [<path>...]`::
|
||||
+
|
||||
--
|
||||
Update the registered submodules to match what the superproject
|
||||
|
|
@ -148,38 +148,38 @@ in submodules and updating the working tree of
|
|||
the submodules. The "updating" can be done in several ways depending
|
||||
on command line options and the value of `submodule.<name>.update`
|
||||
configuration variable. The command line option takes precedence over
|
||||
the configuration variable. If neither is given, a 'checkout' is performed.
|
||||
the configuration variable. If neither is given, a `checkout` is performed.
|
||||
(note: what is in `.gitmodules` file is irrelevant at this point;
|
||||
see `git submodule init` above for how `.gitmodules` is used).
|
||||
The 'update' procedures supported both from the command line as well as
|
||||
The `update` procedures supported both from the command line as well as
|
||||
through the `submodule.<name>.update` configuration are:
|
||||
|
||||
checkout;; the commit recorded in the superproject will be
|
||||
checked out in the submodule on a detached HEAD.
|
||||
`checkout`;; the commit recorded in the superproject will be
|
||||
checked out in the submodule on a detached `HEAD`.
|
||||
+
|
||||
If `--force` is specified, the submodule will be checked out (using
|
||||
`git checkout --force`), even if the commit specified
|
||||
in the index of the containing repository already matches the commit
|
||||
checked out in the submodule.
|
||||
|
||||
rebase;; the current branch of the submodule will be rebased
|
||||
onto the commit recorded in the superproject.
|
||||
`rebase`;; the current branch of the submodule will be rebased
|
||||
onto the commit recorded in the superproject.
|
||||
|
||||
merge;; the commit recorded in the superproject will be merged
|
||||
into the current branch in the submodule.
|
||||
`merge`;; the commit recorded in the superproject will be merged
|
||||
into the current branch in the submodule.
|
||||
|
||||
The following update procedures have additional limitations:
|
||||
|
||||
custom command;; mechanism for running arbitrary commands with the
|
||||
commit ID as an argument. Specifically, if the
|
||||
`submodule.<name>.update` configuration variable is set to
|
||||
`!custom command`, the object name of the commit recorded in the
|
||||
superproject for the submodule is appended to the `custom command`
|
||||
string and executed. Note that this mechanism is not supported in
|
||||
the `.gitmodules` file or on the command line.
|
||||
`!<custom-command>`;; mechanism for running arbitrary commands with the
|
||||
commit ID as an argument. Specifically, if the
|
||||
`submodule.<name>.update` configuration variable is set to
|
||||
`!<custom-command>`, the object name of the commit recorded in the
|
||||
superproject for the submodule is appended to the _<custom-command>_
|
||||
string and executed. Note that this mechanism is not supported in
|
||||
the `.gitmodules` file or on the command line.
|
||||
|
||||
none;; the submodule is not updated. This update procedure is not
|
||||
allowed on the command line.
|
||||
`none`;; the submodule is not updated. This update procedure is not
|
||||
allowed on the command line.
|
||||
|
||||
If the submodule is not yet initialized, and you just want to use the
|
||||
setting as stored in `.gitmodules`, you can automatically initialize the
|
||||
|
|
@ -195,20 +195,20 @@ If `--filter <filter-spec>` is specified, the given partial clone filter will be
|
|||
applied to the submodule. See linkgit:git-rev-list[1] for details on filter
|
||||
specifications.
|
||||
--
|
||||
set-branch (-b|--branch) <branch> [--] <path>::
|
||||
set-branch (-d|--default) [--] <path>::
|
||||
Sets the default remote tracking branch for the submodule. The
|
||||
`set-branch (-b|--branch) <branch> [--] <path>`::
|
||||
`set-branch (-d|--default) [--] <path>`::
|
||||
Set the default remote tracking branch for the submodule. The
|
||||
`--branch` option allows the remote branch to be specified. The
|
||||
`--default` option removes the submodule.<name>.branch configuration
|
||||
key, which causes the tracking branch to default to the remote 'HEAD'.
|
||||
`--default` option removes the `submodule.<name>.branch` configuration
|
||||
key, which causes the tracking branch to default to the remote `HEAD`.
|
||||
|
||||
set-url [--] <path> <newurl>::
|
||||
Sets the URL of the specified submodule to <newurl>. Then, it will
|
||||
`set-url [--] <path> <newurl>`::
|
||||
Set the URL of the specified submodule to _<newurl>_. Then, it will
|
||||
automatically synchronize the submodule's new remote URL
|
||||
configuration.
|
||||
|
||||
summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]::
|
||||
Show commit summary between the given commit (defaults to HEAD) and
|
||||
`summary [--cached | --files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]`::
|
||||
Show commit summary between the given commit (defaults to `HEAD`) and
|
||||
working tree/index. For a submodule in question, a series of commits
|
||||
in the submodule between the given super project commit and the
|
||||
index or working tree (switched by `--cached`) are shown. If the option
|
||||
|
|
@ -220,27 +220,31 @@ summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]:
|
|||
Using the `--submodule=log` option with linkgit:git-diff[1] will provide that
|
||||
information too.
|
||||
|
||||
foreach [--recursive] <command>::
|
||||
Evaluates an arbitrary shell command in each checked out submodule.
|
||||
The command has access to the variables $name, $sm_path, $displaypath,
|
||||
$sha1 and $toplevel:
|
||||
$name is the name of the relevant submodule section in `.gitmodules`,
|
||||
$sm_path is the path of the submodule as recorded in the immediate
|
||||
superproject, $displaypath contains the relative path from the
|
||||
current working directory to the submodules root directory,
|
||||
$sha1 is the commit as recorded in the immediate
|
||||
superproject, and $toplevel is the absolute path to the top-level
|
||||
of the immediate superproject.
|
||||
Note that to avoid conflicts with '$PATH' on Windows, the '$path'
|
||||
variable is now a deprecated synonym of '$sm_path' variable.
|
||||
Any submodules defined in the superproject but not checked out are
|
||||
ignored by this command. Unless given `--quiet`, foreach prints the name
|
||||
of each submodule before evaluating the command.
|
||||
If `--recursive` is given, submodules are traversed recursively (i.e.
|
||||
the given shell command is evaluated in nested submodules as well).
|
||||
A non-zero return from the command in any submodule causes
|
||||
the processing to terminate. This can be overridden by adding '|| :'
|
||||
to the end of the command.
|
||||
`foreach [--recursive] <command>`::
|
||||
Evaluate an arbitrary shell _<command>_ in each checked out submodule.
|
||||
The command has access to the variables `$name`, `$sm_path`, `$displaypath`,
|
||||
`$sha1` and `$toplevel`:
|
||||
+
|
||||
--
|
||||
`$name`;; the name of the relevant submodule section in `.gitmodules`
|
||||
`$sm_path`;; the path of the submodule as recorded in the immediate
|
||||
superproject
|
||||
`$displaypath`;; the relative path from the
|
||||
current working directory to the submodules root directory
|
||||
`$sha1`;; the commit as recorded in the immediate superproject
|
||||
`$toplevel`;; the absolute path to the top-level of the immediate superproject.
|
||||
--
|
||||
+
|
||||
Note that to avoid conflicts with `$PATH` on Windows, the `$path`
|
||||
variable is now a deprecated synonym of `$sm_path` variable.
|
||||
Any submodules defined in the superproject but not checked out are
|
||||
ignored by this command. Unless given `--quiet`, foreach prints the name
|
||||
of each submodule before evaluating the command.
|
||||
If `--recursive` is given, submodules are traversed recursively (i.e.
|
||||
the given shell command is evaluated in nested submodules as well).
|
||||
A non-zero return from the command in any submodule causes
|
||||
the processing to terminate. This can be overridden by adding ++||:++
|
||||
to the end of the command.
|
||||
+
|
||||
As an example, the command below will show the path and currently
|
||||
checked out commit for each submodule:
|
||||
|
|
@ -249,26 +253,26 @@ checked out commit for each submodule:
|
|||
git submodule foreach 'echo $sm_path `git rev-parse HEAD`'
|
||||
--------------
|
||||
|
||||
sync [--recursive] [--] [<path>...]::
|
||||
Synchronizes submodules' remote URL configuration setting
|
||||
`sync [--recursive] [--] [<path>...]`::
|
||||
Synchronize submodules' remote URL configuration setting
|
||||
to the value specified in `.gitmodules`. It will only affect those
|
||||
submodules which already have a URL entry in .git/config (that is the
|
||||
submodules which already have a URL entry in `.git/config` (that is the
|
||||
case when they are initialized or freshly added). This is useful when
|
||||
submodule URLs change upstream and you need to update your local
|
||||
repositories accordingly.
|
||||
+
|
||||
`git submodule sync` synchronizes all submodules while
|
||||
`git submodule sync -- A` synchronizes submodule "A" only.
|
||||
`git submodule sync -- A` synchronizes submodule `A` only.
|
||||
+
|
||||
If `--recursive` is specified, this command will recurse into the
|
||||
registered submodules, and sync any nested submodules within.
|
||||
|
||||
absorbgitdirs::
|
||||
`absorbgitdirs`::
|
||||
If a git directory of a submodule is inside the submodule,
|
||||
move the git directory of the submodule into its superproject's
|
||||
`$GIT_DIR/modules` path and then connect the git directory and
|
||||
its working directory by setting the `core.worktree` and adding
|
||||
a .git file pointing to the git directory embedded in the
|
||||
a `.git` file pointing to the git directory embedded in the
|
||||
superprojects git directory.
|
||||
+
|
||||
A repository that was cloned independently and later added as a submodule or
|
||||
|
|
@ -279,72 +283,70 @@ This command is recursive by default.
|
|||
|
||||
OPTIONS
|
||||
-------
|
||||
-q::
|
||||
--quiet::
|
||||
`-q`::
|
||||
`--quiet`::
|
||||
Only print error messages.
|
||||
|
||||
--progress::
|
||||
This option is only valid for add and update commands.
|
||||
Progress status is reported on the standard error stream
|
||||
by default when it is attached to a terminal, unless -q
|
||||
`--progress`::
|
||||
Report progress status on the standard error stream
|
||||
by default when it is attached to a terminal, unless `-q`
|
||||
is specified. This flag forces progress status even if the
|
||||
standard error stream is not directed to a terminal.
|
||||
standard error stream is not directed to a terminal. It is
|
||||
only valid for `add` and `update` commands.
|
||||
|
||||
--all::
|
||||
This option is only valid for the deinit command. Unregister all
|
||||
submodules in the working tree.
|
||||
`--all`::
|
||||
Unregister all submodules in the working tree. This option is only
|
||||
valid for the `deinit` command.
|
||||
|
||||
-b <branch>::
|
||||
--branch <branch>::
|
||||
`-b<branch>`::
|
||||
`--branch=<branch>`::
|
||||
Branch of repository to add as submodule.
|
||||
The name of the branch is recorded as `submodule.<name>.branch` in
|
||||
`.gitmodules` for `update --remote`. A special value of `.` is used to
|
||||
indicate that the name of the branch in the submodule should be the
|
||||
same name as the current branch in the current repository. If the
|
||||
option is not specified, it defaults to the remote 'HEAD'.
|
||||
option is not specified, it defaults to the remote `HEAD`.
|
||||
|
||||
-f::
|
||||
--force::
|
||||
This option is only valid for add, deinit and update commands.
|
||||
When running add, allow adding an otherwise ignored submodule path.
|
||||
This option is also used to bypass a check that the submodule's name
|
||||
is not already in use. By default, 'git submodule add' will fail if
|
||||
the proposed name (which is derived from the path) is already registered
|
||||
for another submodule in the repository. Using '--force' allows the command
|
||||
to proceed by automatically generating a unique name by appending a number
|
||||
to the conflicting name (e.g., if a submodule named 'child' exists, it will
|
||||
try 'child1', and so on).
|
||||
When running deinit the submodule working trees will be removed even
|
||||
if they contain local changes.
|
||||
When running update (only effective with the checkout procedure),
|
||||
throw away local changes in submodules when switching to a
|
||||
different commit; and always run a checkout operation in the
|
||||
submodule, even if the commit listed in the index of the
|
||||
containing repository matches the commit checked out in the
|
||||
submodule.
|
||||
`-f`::
|
||||
`--force`::
|
||||
Force the command to proceed, even if it would otherwise fail.
|
||||
This option is only valid for `add`, `deinit` and `update` commands.
|
||||
`add`;; allow adding an otherwise ignored submodule path.
|
||||
This option is also used to bypass a check that the submodule's name
|
||||
is not already in use. By default, `git submodule add` will fail if
|
||||
the proposed name (which is derived from the path) is already registered
|
||||
for another submodule in the repository. Using `--force` allows the command
|
||||
to proceed by automatically generating a unique name by appending a number
|
||||
to the conflicting name (e.g., if a submodule named 'child' exists, it will
|
||||
try 'child1', and so on).
|
||||
`deinit`;; the submodule working trees will be removed even
|
||||
if they contain local changes.
|
||||
`update`;; (only effective with the checkout procedure),
|
||||
throw away local changes in submodules when switching to a
|
||||
different commit; and always run a checkout operation in the
|
||||
submodule, even if the commit listed in the index of the
|
||||
containing repository matches the commit checked out in the
|
||||
submodule.
|
||||
|
||||
--cached::
|
||||
This option is only valid for status and summary commands. These
|
||||
commands typically use the commit found in the submodule HEAD, but
|
||||
with this option, the commit stored in the index is used instead.
|
||||
`--cached`::
|
||||
Use the index to determine the commit instead of the `HEAD`.
|
||||
This option is only valid for `status` and `summary` commands.
|
||||
|
||||
--files::
|
||||
This option is only valid for the summary command. This command
|
||||
compares the commit in the index with that in the submodule HEAD
|
||||
when this option is used.
|
||||
`--files`::
|
||||
Make the `summary` command compare the commit in the index with that in
|
||||
the submodule `HEAD`.
|
||||
|
||||
-n::
|
||||
--summary-limit::
|
||||
This option is only valid for the summary command.
|
||||
Limit the summary size (number of commits shown in total).
|
||||
`-n<n>`::
|
||||
`--summary-limit=<n>`::
|
||||
Limit the `summary` size (number of commits shown in total) to _<n>_.
|
||||
Giving 0 will disable the summary; a negative number means unlimited
|
||||
(the default). This limit only applies to modified submodules. The
|
||||
size is always limited to 1 for added/deleted/typechanged submodules.
|
||||
|
||||
--remote::
|
||||
This option is only valid for the update command. Instead of using
|
||||
the superproject's recorded SHA-1 to update the submodule, use the
|
||||
status of the submodule's remote-tracking branch. The remote used
|
||||
`--remote`::
|
||||
Instead of using the superproject's recorded SHA-1 to update the
|
||||
submodule, use the status of the submodule's remote-tracking branch.
|
||||
This option is only valid for the `update` command. The remote used
|
||||
is branch's remote (`branch.<name>.remote`), defaulting to `origin`.
|
||||
The remote branch used defaults to the remote `HEAD`, but the branch
|
||||
name may be overridden by setting the `submodule.<name>.branch`
|
||||
|
|
@ -363,7 +365,7 @@ SHA-1. If you don't want to fetch, you should use `submodule update
|
|||
--remote --no-fetch`.
|
||||
+
|
||||
Use this option to integrate changes from the upstream subproject with
|
||||
your submodule's current HEAD. Alternatively, you can run `git pull`
|
||||
your submodule's current `HEAD`. Alternatively, you can run `git pull`
|
||||
from the submodule, which is equivalent except for the remote branch
|
||||
name: `update --remote` uses the default upstream repository and
|
||||
`submodule.<name>.branch`, while `git pull` uses the submodule's
|
||||
|
|
@ -372,105 +374,106 @@ to distribute the default upstream branch with the superproject and
|
|||
`branch.<name>.merge` if you want a more native feel while working in
|
||||
the submodule itself.
|
||||
|
||||
-N::
|
||||
--no-fetch::
|
||||
This option is only valid for the update command.
|
||||
`-N`::
|
||||
`--no-fetch`::
|
||||
Don't fetch new objects from the remote site.
|
||||
This option is only valid for the `update` command.
|
||||
|
||||
--checkout::
|
||||
This option is only valid for the update command.
|
||||
Checkout the commit recorded in the superproject on a detached HEAD
|
||||
in the submodule. This is the default behavior, the main use of
|
||||
this option is to override `submodule.$name.update` when set to
|
||||
`--checkout`::
|
||||
Checkout the commit recorded in the superproject on a detached `HEAD`
|
||||
in the submodule. This option is only valid for the `update` command.
|
||||
This is the default behavior, the main use of
|
||||
this option is to override `submodule.<name>.update` when set to
|
||||
a value other than `checkout`.
|
||||
If the key `submodule.$name.update` is either not explicitly set or
|
||||
If the key `submodule.<name>.update` is either not explicitly set or
|
||||
set to `checkout`, this option is implicit.
|
||||
|
||||
--merge::
|
||||
This option is only valid for the update command.
|
||||
`--merge`::
|
||||
Merge the commit recorded in the superproject into the current branch
|
||||
of the submodule. If this option is given, the submodule's HEAD will
|
||||
of the submodule. This option is only valid for the `update` command.
|
||||
If this option is given, the submodule's `HEAD` will
|
||||
not be detached. If a merge failure prevents this process, you will
|
||||
have to resolve the resulting conflicts within the submodule with the
|
||||
usual conflict resolution tools.
|
||||
If the key `submodule.$name.update` is set to `merge`, this option is
|
||||
If the key `submodule.<name>.update` is set to `merge`, this option is
|
||||
implicit.
|
||||
|
||||
--rebase::
|
||||
This option is only valid for the update command.
|
||||
Rebase the current branch onto the commit recorded in the
|
||||
superproject. If this option is given, the submodule's HEAD will not
|
||||
`--rebase`::
|
||||
Rebase the current branch onto the commit recorded in the superproject.
|
||||
This option is only valid for the `update` command. The submodule's `HEAD` will not
|
||||
be detached. If a merge failure prevents this process, you will have
|
||||
to resolve these failures with linkgit:git-rebase[1].
|
||||
If the key `submodule.$name.update` is set to `rebase`, this option is
|
||||
If the key `submodule.<name>.update` is set to `rebase`, this option is
|
||||
implicit.
|
||||
|
||||
--init::
|
||||
This option is only valid for the update command.
|
||||
Initialize all submodules for which "git submodule init" has not been
|
||||
called so far before updating.
|
||||
`--init`::
|
||||
Initialize all submodules for which `git submodule init` has not been
|
||||
called so far before updating. This option is only valid for the `update`
|
||||
command.
|
||||
|
||||
--name::
|
||||
This option is only valid for the add command. It sets the submodule's
|
||||
name to the given string instead of defaulting to its path. The name
|
||||
must be valid as a directory name and may not end with a '/'.
|
||||
|
||||
--reference <repository>::
|
||||
This option is only valid for add and update commands. These
|
||||
commands sometimes need to clone a remote repository. In this case,
|
||||
`--name=<name>`::
|
||||
Set the submodule's name to the given string instead of defaulting to its path. _<name>_
|
||||
must be valid as a directory name and may not end with a `/`.
|
||||
|
||||
`--reference=<repository>`::
|
||||
Pass the local _<repository>_ as a reference when cloning the submodule.
|
||||
This option is only valid for `add` and `update` commands.
|
||||
These commands sometimes need to clone a remote repository. In this case,
|
||||
this option will be passed to the linkgit:git-clone[1] command.
|
||||
+
|
||||
*NOTE*: Do *not* use this option unless you have read the note
|
||||
NOTE: Do *not* use this option unless you have read the note
|
||||
for linkgit:git-clone[1]'s `--reference`, `--shared`, and `--dissociate`
|
||||
options carefully.
|
||||
|
||||
--dissociate::
|
||||
This option is only valid for add and update commands. These
|
||||
commands sometimes need to clone a remote repository. In this case,
|
||||
`--dissociate`::
|
||||
After using a reference repository to clone from, do not rely on it anymore.
|
||||
This option is only valid for `add` and `update` commands.
|
||||
These commands sometimes need to clone a remote repository. In this case,
|
||||
this option will be passed to the linkgit:git-clone[1] command.
|
||||
+
|
||||
*NOTE*: see the NOTE for the `--reference` option.
|
||||
NOTE: See the NOTE above for the `--reference` option.
|
||||
|
||||
--recursive::
|
||||
This option is only valid for foreach, update, status and sync commands.
|
||||
Traverse submodules recursively. The operation is performed not
|
||||
`--recursive`::
|
||||
Traverse submodules recursively. This option is only valid for `foreach`,
|
||||
`update`, `status` and `sync` commands. The operation is performed not
|
||||
only in the submodules of the current repo, but also
|
||||
in any nested submodules inside those submodules (and so on).
|
||||
|
||||
--depth::
|
||||
This option is valid for add and update commands. Create a 'shallow'
|
||||
clone with a history truncated to the specified number of revisions.
|
||||
See linkgit:git-clone[1]
|
||||
`--depth=<depth>`::
|
||||
Create a 'shallow' clone with a history truncated to the _<depth>_ revisions.
|
||||
This option is valid for `add` and `update` commands. See linkgit:git-clone[1]
|
||||
|
||||
--recommend-shallow::
|
||||
--no-recommend-shallow::
|
||||
This option is only valid for the update command.
|
||||
`--recommend-shallow`::
|
||||
`--no-recommend-shallow`::
|
||||
Recommend or not shallow cloning of submodules.
|
||||
This option is only valid for the `update` command.
|
||||
The initial clone of a submodule will use the recommended
|
||||
`submodule.<name>.shallow` as provided by the `.gitmodules` file
|
||||
by default. To ignore the suggestions use `--no-recommend-shallow`.
|
||||
|
||||
-j <n>::
|
||||
--jobs <n>::
|
||||
This option is only valid for the update command.
|
||||
Clone new submodules in parallel with as many jobs.
|
||||
`-j<n>`::
|
||||
`--jobs=<n>`::
|
||||
Clone new submodules in parallel with _<n>_ jobs.
|
||||
This option is only valid for the `update` command.
|
||||
Defaults to the `submodule.fetchJobs` option.
|
||||
|
||||
--single-branch::
|
||||
--no-single-branch::
|
||||
This option is only valid for the update command.
|
||||
Clone only one branch during update: HEAD or one specified by --branch.
|
||||
`--single-branch`::
|
||||
`--no-single-branch`::
|
||||
Clone only one branch during update: `HEAD` or one specified by `--branch`.
|
||||
This option is only valid for the `update` command.
|
||||
|
||||
<path>...::
|
||||
`<path>...`::
|
||||
Paths to submodule(s). When specified this will restrict the command
|
||||
to only operate on the submodules found at the specified paths.
|
||||
(This argument is required with add).
|
||||
(This argument is required with `add`).
|
||||
|
||||
FILES
|
||||
-----
|
||||
When initializing submodules, a `.gitmodules` file in the top-level directory
|
||||
of the containing repository is used to find the url of each submodule.
|
||||
of the containing repository is used to find the URL of each submodule.
|
||||
This file should be formatted in the same way as `$GIT_DIR/config`. The key
|
||||
to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5]
|
||||
to each submodule URL is `submodule.<name>.url`. See linkgit:gitmodules[5]
|
||||
for details.
|
||||
|
||||
SEE ALSO
|
||||
|
|
|
|||
Loading…
Reference in New Issue