Merge branch 'sb/submodule-doc'
Doc updates. * sb/submodule-doc: submodule update documentation: don't repeat ourselves submodule documentation: add options to the subcommand
This commit is contained in:
Junio C Hamano
commit
2f4e87d777
@ -9,17 +9,12 @@ git-submodule - Initialize, update or inspect submodules
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>]
|
||||
[--reference <repository>] [--depth <depth>] [--] <repository> [<path>]
|
||||
'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 [--init] [--remote] [-N|--no-fetch]
|
||||
[--[no-]recommend-shallow] [-f|--force] [--rebase|--merge]
|
||||
[--reference <repository>] [--depth <depth>] [--recursive]
|
||||
[--jobs <n>] [--] [<path>...]
|
||||
'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
|
||||
[commit] [--] [<path>...]
|
||||
'git submodule' [--quiet] update [<options>] [--] [<path>...]
|
||||
'git submodule' [--quiet] summary [<options>] [--] [<path>...]
|
||||
'git submodule' [--quiet] foreach [--recursive] <command>
|
||||
'git submodule' [--quiet] sync [--recursive] [--] [<path>...]
|
||||
'git submodule' [--quiet] absorbgitdirs [--] [<path>...]
|
||||
@ -63,7 +58,7 @@ if you choose to go that route.
|
||||
|
||||
COMMANDS
|
||||
--------
|
||||
add::
|
||||
add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--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".
|
||||
@ -104,7 +99,7 @@ together in the same relative location, and only the
|
||||
superproject's URL needs to be provided: git-submodule will correctly
|
||||
locate the submodule using the relative URL in .gitmodules.
|
||||
|
||||
status::
|
||||
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
|
||||
@ -121,7 +116,7 @@ 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::
|
||||
init [--] [<path>...]::
|
||||
Initialize the submodules recorded in the index (which were
|
||||
added and committed elsewhere) by copying submodule
|
||||
names and urls from .gitmodules to .git/config.
|
||||
@ -136,7 +131,7 @@ init::
|
||||
the explicit 'init' step if you do not intend to customize
|
||||
any submodule locations.
|
||||
|
||||
deinit::
|
||||
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`
|
||||
@ -152,20 +147,20 @@ instead of deinit-ing everything, to prevent mistakes.
|
||||
If `--force` is specified, the submodule's working tree will
|
||||
be removed even if it contains local modifications.
|
||||
|
||||
update::
|
||||
update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...]::
|
||||
+
|
||||
--
|
||||
Update the registered submodules to match what the superproject
|
||||
expects by cloning missing 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. Supported update procedures are:
|
||||
configuration variable. The command line option takes precedence over
|
||||
the configuration variable. if neither is given, a checkout is performed.
|
||||
update procedures supported both from the command line as well as setting
|
||||
`submodule.<name>.update`:
|
||||
|
||||
checkout;; the commit recorded in the superproject will be
|
||||
checked out in the submodule on a detached HEAD. This is
|
||||
done when `--checkout` option is given, or no option is
|
||||
given, and `submodule.<name>.update` is unset, or if it is
|
||||
set to 'checkout'.
|
||||
checked out in the submodule on a detached HEAD.
|
||||
+
|
||||
If `--force` is specified, the submodule will be checked out (using
|
||||
`git checkout --force` if appropriate), even if the commit specified
|
||||
@ -173,23 +168,21 @@ 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. This is done
|
||||
when `--rebase` option is given, or no option is given, and
|
||||
`submodule.<name>.update` is set to 'rebase'.
|
||||
onto the commit recorded in the superproject.
|
||||
|
||||
merge;; the commit recorded in the superproject will be merged
|
||||
into the current branch in the submodule. This is done
|
||||
when `--merge` option is given, or no option is given, and
|
||||
`submodule.<name>.update` is set to 'merge'.
|
||||
into the current branch in the submodule.
|
||||
|
||||
The following procedures are only available via the `submodule.<name>.update`
|
||||
configuration variable:
|
||||
|
||||
custom command;; arbitrary shell command that takes a single
|
||||
argument (the sha1 of the commit recorded in the
|
||||
superproject) is executed. This is done when no option is
|
||||
given, and `submodule.<name>.update` has the form of
|
||||
'!command'.
|
||||
superproject) is executed. When `submodule.<name>.update`
|
||||
is set to '!command', the remainder after the exclamation mark
|
||||
is the custom command.
|
||||
|
||||
When no option is given and `submodule.<name>.update` is set to 'none',
|
||||
the submodule is not updated.
|
||||
none;; the submodule is not updated.
|
||||
|
||||
If the submodule is not yet initialized, and you just want to use the
|
||||
setting as stored in .gitmodules, you can automatically initialize the
|
||||
@ -198,7 +191,7 @@ submodule with the `--init` option.
|
||||
If `--recursive` is specified, this command will recurse into the
|
||||
registered submodules, and update any nested submodules within.
|
||||
--
|
||||
summary::
|
||||
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
|
||||
@ -211,7 +204,7 @@ summary::
|
||||
Using the `--submodule=log` option with linkgit:git-diff[1] will provide that
|
||||
information too.
|
||||
|
||||
foreach::
|
||||
foreach [--recursive] <command>::
|
||||
Evaluates an arbitrary shell command in each checked out submodule.
|
||||
The command has access to the variables $name, $path, $sha1 and
|
||||
$toplevel:
|
||||
@ -232,7 +225,7 @@ As an example, +git submodule foreach \'echo $path {backtick}git
|
||||
rev-parse HEAD{backtick}'+ will show the path and currently checked out
|
||||
commit for each submodule.
|
||||
|
||||
sync::
|
||||
sync [--recursive] [--] [<path>...]::
|
||||
Synchronizes 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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user