mirror of
https://github.com/git/git.git
synced 2026-03-05 06:57:37 +01:00
Merge branch 'ja/doc-synopsis-style-even-more' into next
A handful of documentation pages have been modernized to use the "synopsis" style. * ja/doc-synopsis-style-even-more: doc: convert git-show to synopsis style doc: fix some style issues in git-clone and for-each-ref-options doc: finalize git-clone documentation conversion to synopsis style doc: convert git-submodule to synopsis style
This commit is contained in:
Junio C Hamano
@@ -81,12 +81,18 @@ endif::backend-xhtml11[]
|
||||
|
||||
ifdef::backend-docbook[]
|
||||
ifdef::doctype-manpage[]
|
||||
[blockdef-open]
|
||||
synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]\\+>!<emphasis>\\0</emphasis>!g'"
|
||||
|
||||
[paradef-default]
|
||||
synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]\\+>!<emphasis>\\0</emphasis>!g'"
|
||||
endif::doctype-manpage[]
|
||||
endif::backend-docbook[]
|
||||
|
||||
ifdef::backend-xhtml11[]
|
||||
[blockdef-open]
|
||||
synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]\\+>!<em>\\0</em>!g'"
|
||||
|
||||
[paradef-default]
|
||||
synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]\\+>!<em>\\0</em>!g'"
|
||||
endif::backend-xhtml11[]
|
||||
|
||||
@@ -30,8 +30,8 @@ TAB %(refname)`.
|
||||
|
||||
`--color[=<when>]`::
|
||||
Respect any colors specified in the `--format` option. The
|
||||
_<when__ field must be one of `always`, `never`, or `auto` (if
|
||||
`<when>` is absent, behave as if `always` was given).
|
||||
_<when>_ field must be one of `always`, `never`, or `auto` (if
|
||||
_<when>_ is absent, behave as if `always` was given).
|
||||
|
||||
`--shell`::
|
||||
`--perl`::
|
||||
|
||||
@@ -84,7 +84,7 @@ _<src>_.
|
||||
with the source repository. The resulting repository
|
||||
starts out without any object of its own.
|
||||
+
|
||||
*NOTE*: this is a possibly dangerous operation; do *not* use
|
||||
NOTE: this is a possibly dangerous operation; do *not* use
|
||||
it unless you understand what it does. If you clone your
|
||||
repository using this option and then delete branches (or use any
|
||||
other Git command that makes any existing commit unreferenced) in the
|
||||
@@ -104,7 +104,8 @@ If you want to break the dependency of a repository cloned with `--shared` on
|
||||
its source repository, you can simply run `git repack -a` to copy all
|
||||
objects from the source repository into a pack in the cloned repository.
|
||||
|
||||
`--reference[-if-able] <repository>`::
|
||||
`--reference=<repository>`::
|
||||
`--reference-if-able=<repository>`::
|
||||
If the reference _<repository>_ is on the local machine,
|
||||
automatically setup `.git/objects/info/alternates` to
|
||||
obtain objects from the reference _<repository>_. Using
|
||||
@@ -115,7 +116,7 @@ objects from the source repository into a pack in the cloned repository.
|
||||
directory is skipped with a warning instead of aborting
|
||||
the clone.
|
||||
+
|
||||
*NOTE*: see the NOTE for the `--shared` option, and also the
|
||||
NOTE: see the NOTE for the `--shared` option, and also the
|
||||
`--dissociate` option.
|
||||
|
||||
`--dissociate`::
|
||||
@@ -140,27 +141,28 @@ objects from the source repository into a pack in the cloned repository.
|
||||
to the standard error stream.
|
||||
|
||||
`--progress`::
|
||||
Progress status is reported on the standard error stream
|
||||
by default when it is attached to a terminal, unless `--quiet`
|
||||
Report progress status on the standard error stream
|
||||
by default when attached to a terminal, unless `--quiet`
|
||||
is specified. This flag forces progress status even if the
|
||||
standard error stream is not directed to a terminal.
|
||||
|
||||
`--server-option=<option>`::
|
||||
Transmit the given string to the server when communicating using
|
||||
protocol version 2. The given string must not contain a NUL or LF
|
||||
protocol version 2. The given string must not contain a _NUL_ or _LF_
|
||||
character. The server's handling of server options, including
|
||||
unknown ones, is server-specific.
|
||||
When multiple `--server-option=<option>` are given, they are all
|
||||
sent to the other side in the order listed on the command line.
|
||||
When no ++--server-option=++__<option>__ is given from the command
|
||||
When no `--server-option=<option>` is given from the command
|
||||
line, the values of configuration variable `remote.<name>.serverOption`
|
||||
are used instead.
|
||||
|
||||
`-n`::
|
||||
`--no-checkout`::
|
||||
No checkout of `HEAD` is performed after the clone is complete.
|
||||
Do not checkout `HEAD` after the clone is complete.
|
||||
|
||||
`--`[`no-`]`reject-shallow`::
|
||||
`--no-reject-shallow`::
|
||||
`--reject-shallow`::
|
||||
Fail if the source repository is a shallow repository.
|
||||
The `clone.rejectShallow` configuration variable can be used to
|
||||
specify the default.
|
||||
@@ -206,18 +208,17 @@ objects from the source repository into a pack in the cloned repository.
|
||||
that all these refs are overwritten by a `git remote update` in the
|
||||
target repository.
|
||||
|
||||
`-o` _<name>_::
|
||||
`--origin` _<name>_::
|
||||
`-o<name>`::
|
||||
`--origin=<name>`::
|
||||
Instead of using the remote name `origin` to keep track of the upstream
|
||||
repository, use _<name>_. Overrides `clone.defaultRemoteName` from the
|
||||
config.
|
||||
|
||||
`-b` _<name>_::
|
||||
`--branch` _<name>_::
|
||||
Instead of pointing the newly created `HEAD` to the branch pointed
|
||||
to by the cloned repository's `HEAD`, point to _<name>_ branch
|
||||
instead. In a non-bare repository, this is the branch that will
|
||||
be checked out.
|
||||
`-b<name>`::
|
||||
`--branch=<name>`::
|
||||
Point the newly created `HEAD` to _<name>_ branch instead of the branch
|
||||
pointed to by the cloned repository's `HEAD`. In a non-bare repository,
|
||||
this is the branch that will be checked out.
|
||||
`--branch` can also take tags and detaches the `HEAD` at that commit
|
||||
in the resulting repository.
|
||||
|
||||
@@ -230,18 +231,17 @@ objects from the source repository into a pack in the cloned repository.
|
||||
name.
|
||||
This option is incompatible with `--branch` and `--mirror`.
|
||||
|
||||
`-u` _<upload-pack>_::
|
||||
`--upload-pack` _<upload-pack>_::
|
||||
When given, and the repository to clone from is accessed
|
||||
via ssh, this specifies a non-default path for the command
|
||||
run on the other end.
|
||||
`-u<upload-pack>`::
|
||||
`--upload-pack=<upload-pack>`::
|
||||
Specify a non-default path for the command run on the other end when the
|
||||
repository to clone from is accessed via ssh.
|
||||
|
||||
`--template=<template-directory>`::
|
||||
Specify the directory from which templates will be used;
|
||||
(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
|
||||
|
||||
`-c` `<key>=<value>`::
|
||||
`--config` `<key>=<value>`::
|
||||
`-c<key>=<value>`::
|
||||
`--config=<key>=<value>`::
|
||||
Set a configuration variable in the newly-created repository;
|
||||
this takes effect immediately after the repository is
|
||||
initialized, but before the remote history is fetched or any
|
||||
@@ -257,7 +257,7 @@ Configuration variables known to not take effect are:
|
||||
`remote.<name>.mirror` and `remote.<name>.tagOpt`. Use the
|
||||
corresponding `--mirror` and `--no-tags` options instead.
|
||||
|
||||
`--depth <depth>`::
|
||||
`--depth=<depth>`::
|
||||
Create a 'shallow' clone with a history truncated to the
|
||||
specified number of commits. Implies `--single-branch` unless
|
||||
`--no-single-branch` is given to fetch the histories near the
|
||||
@@ -339,8 +339,8 @@ Specify the given ref storage format for the repository. The valid values are:
|
||||
+
|
||||
include::ref-storage-format.adoc[]
|
||||
|
||||
`-j` _<n>_::
|
||||
`--jobs` _<n>_::
|
||||
`-j<n>`::
|
||||
`--jobs=<n>`::
|
||||
The number of submodules fetched at the same time.
|
||||
Defaults to the `submodule.fetchJobs` option.
|
||||
|
||||
|
||||
@@ -8,8 +8,8 @@ git-show - Show various types of objects
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
'git show' [<options>] [<object>...]
|
||||
[synopsis]
|
||||
git show [<options>] [<object>...]
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
@@ -17,16 +17,16 @@ Shows one or more objects (blobs, trees, tags and commits).
|
||||
|
||||
For commits it shows the log message and textual diff. It also
|
||||
presents the merge commit in a special format as produced by
|
||||
'git diff-tree --cc'.
|
||||
`git diff-tree --cc`.
|
||||
|
||||
For tags, it shows the tag message and the referenced objects.
|
||||
|
||||
For trees, it shows the names (equivalent to 'git ls-tree'
|
||||
with --name-only).
|
||||
For trees, it shows the names (equivalent to `git ls-tree`
|
||||
with `--name-only`).
|
||||
|
||||
For plain blobs, it shows the plain contents.
|
||||
|
||||
Some options that 'git log' command understands can be used to
|
||||
Some options that `git log` command understands can be used to
|
||||
control how the changes the commit introduces are shown.
|
||||
|
||||
This manual page describes only the most frequently used options.
|
||||
@@ -34,8 +34,8 @@ This manual page describes only the most frequently used options.
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
<object>...::
|
||||
The names of objects to show (defaults to 'HEAD').
|
||||
`<object>...`::
|
||||
The names of objects to show (defaults to `HEAD`).
|
||||
For a more complete list of ways to spell object names, see
|
||||
"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -18,54 +18,72 @@ config option to either another format name, or a
|
||||
linkgit:git-config[1]). Here are the details of the
|
||||
built-in formats:
|
||||
|
||||
* `oneline`
|
||||
|
||||
<hash> <title-line>
|
||||
`oneline`::
|
||||
+
|
||||
[synopsis]
|
||||
--
|
||||
<hash> <title-line>
|
||||
--
|
||||
+
|
||||
This is designed to be as compact as possible.
|
||||
|
||||
* `short`
|
||||
`short`::
|
||||
+
|
||||
[synopsis]
|
||||
--
|
||||
commit <hash>
|
||||
Author: <author>
|
||||
|
||||
commit <hash>
|
||||
Author: <author>
|
||||
<title-line>
|
||||
--
|
||||
|
||||
<title-line>
|
||||
`medium`::
|
||||
+
|
||||
[synopsis]
|
||||
--
|
||||
commit <hash>
|
||||
Author: <author>
|
||||
Date: <author-date>
|
||||
|
||||
* `medium`
|
||||
<title-line>
|
||||
|
||||
commit <hash>
|
||||
Author: <author>
|
||||
Date: <author-date>
|
||||
<full-commit-message>
|
||||
--
|
||||
|
||||
<title-line>
|
||||
`full`::
|
||||
+
|
||||
[synopsis]
|
||||
--
|
||||
commit <hash>
|
||||
Author: <author>
|
||||
Commit: <committer>
|
||||
|
||||
<full-commit-message>
|
||||
<title-line>
|
||||
|
||||
* `full`
|
||||
<full-commit-message>
|
||||
--
|
||||
|
||||
commit <hash>
|
||||
Author: <author>
|
||||
Commit: <committer>
|
||||
`fuller`::
|
||||
+
|
||||
[synopsis]
|
||||
--
|
||||
commit <hash>
|
||||
Author: <author>
|
||||
AuthorDate: <author-date>
|
||||
Commit: <committer>
|
||||
CommitDate: <committer-date>
|
||||
|
||||
<title-line>
|
||||
<title-line>
|
||||
|
||||
<full-commit-message>
|
||||
<full-commit-message>
|
||||
--
|
||||
|
||||
* `fuller`
|
||||
|
||||
commit <hash>
|
||||
Author: <author>
|
||||
AuthorDate: <author-date>
|
||||
Commit: <committer>
|
||||
CommitDate: <committer-date>
|
||||
|
||||
<title-line>
|
||||
|
||||
<full-commit-message>
|
||||
|
||||
* `reference`
|
||||
|
||||
<abbrev-hash> (<title-line>, <short-author-date>)
|
||||
`reference`::
|
||||
+
|
||||
[synopsis]
|
||||
--
|
||||
<abbrev-hash> (<title-line>, <short-author-date>)
|
||||
--
|
||||
+
|
||||
This format is used to refer to another commit in a commit message and
|
||||
is the same as ++--pretty=\'format:%C(auto)%h (%s, %ad)'++. By default,
|
||||
@@ -74,23 +92,24 @@ is explicitly specified. As with any `format:` with format
|
||||
placeholders, its output is not affected by other options like
|
||||
`--decorate` and `--walk-reflogs`.
|
||||
|
||||
* `email`
|
||||
|
||||
From <hash> <date>
|
||||
From: <author>
|
||||
Date: <author-date>
|
||||
Subject: [PATCH] <title-line>
|
||||
|
||||
<full-commit-message>
|
||||
|
||||
* `mboxrd`
|
||||
`email`::
|
||||
+
|
||||
[synopsis]
|
||||
--
|
||||
From <hash> <date>
|
||||
From: <author>
|
||||
Date: <author-date>
|
||||
Subject: [PATCH] <title-line>
|
||||
|
||||
<full-commit-message>
|
||||
--
|
||||
|
||||
`mboxrd`::
|
||||
Like `email`, but lines in the commit message starting with "From "
|
||||
(preceded by zero or more ">") are quoted with ">" so they aren't
|
||||
confused as starting a new commit.
|
||||
|
||||
* `raw`
|
||||
+
|
||||
`raw`::
|
||||
The `raw` format shows the entire commit exactly as
|
||||
stored in the commit object. Notably, the hashes are
|
||||
displayed in full, regardless of whether `--abbrev` or
|
||||
@@ -101,8 +120,7 @@ commits are displayed, but not the way the diff is shown e.g. with
|
||||
`git log --raw`. To get full object names in a raw diff format,
|
||||
use `--no-abbrev`.
|
||||
|
||||
* `format:<format-string>`
|
||||
+
|
||||
`format:<format-string>`::
|
||||
The `format:<format-string>` format allows you to specify which information
|
||||
you want to show. It works a little bit like printf format,
|
||||
with the notable exception that you get a newline with `%n`
|
||||
@@ -120,13 +138,18 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
|
||||
The placeholders are:
|
||||
|
||||
- Placeholders that expand to a single literal character:
|
||||
+
|
||||
--
|
||||
++%n++:: newline
|
||||
++%%++:: a raw ++%++
|
||||
++%x00++:: ++%x++ followed by two hexadecimal digits is replaced with a
|
||||
byte with the hexadecimal digits' value (we will call this
|
||||
"literal formatting code" in the rest of this document).
|
||||
--
|
||||
|
||||
- Placeholders that affect formatting of later placeholders:
|
||||
+
|
||||
--
|
||||
++%Cred++:: switch color to red
|
||||
++%Cgreen++:: switch color to green
|
||||
++%Cblue++:: switch color to blue
|
||||
@@ -181,8 +204,11 @@ The placeholders are:
|
||||
++%><|(++_<m>_++)++:: similar to ++%<(++_<n>_++)++, ++%<|(++_<m>_++)++
|
||||
respectively, but padding both sides
|
||||
(i.e. the text is centered)
|
||||
--
|
||||
|
||||
- Placeholders that expand to information extracted from the commit:
|
||||
+
|
||||
--
|
||||
+%H+:: commit hash
|
||||
+%h+:: abbreviated commit hash
|
||||
+%T+:: tree hash
|
||||
@@ -233,20 +259,19 @@ colon and zero or more comma-separated options. Option values may contain
|
||||
literal formatting codes. These must be used for commas (`%x2C`) and closing
|
||||
parentheses (`%x29`), due to their role in the option syntax.
|
||||
|
||||
** `prefix=<value>`: Shown before the list of ref names. Defaults to "{nbsp}++(++".
|
||||
** `suffix=<value>`: Shown after the list of ref names. Defaults to "+)+".
|
||||
** `separator=<value>`: Shown between ref names. Defaults to "+,+{nbsp}".
|
||||
** `pointer=<value>`: Shown between HEAD and the branch it points to, if any.
|
||||
Defaults to "{nbsp}++->++{nbsp}".
|
||||
** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
|
||||
`prefix=<value>`;; Shown before the list of ref names. Defaults to "{nbsp}++(++".
|
||||
`suffix=<value>`;; Shown after the list of ref names. Defaults to "+)+".
|
||||
`separator=<value>`;; Shown between ref names. Defaults to "+,+{nbsp}".
|
||||
`pointer=<value>`;; Shown between HEAD and the branch it points to, if any.
|
||||
Defaults to "{nbsp}->{nbsp}".
|
||||
`tag=<value>`;; Shown before tag names. Defaults to "`tag:`{nbsp}".
|
||||
|
||||
+
|
||||
--
|
||||
For example, to produce decorations with no wrapping
|
||||
or tag annotations, and spaces as separators:
|
||||
|
||||
++%(decorate:prefix=,suffix=,tag=,separator= )++
|
||||
--
|
||||
---------------------
|
||||
%(decorate:prefix=,suffix=,tag=,separator= )
|
||||
---------------------
|
||||
|
||||
++%(describe++`[:<option>,...]`++)++::
|
||||
human-readable name, like linkgit:git-describe[1]; empty string for
|
||||
@@ -254,15 +279,15 @@ undescribable commits. The `describe` string may be followed by a colon and
|
||||
zero or more comma-separated options. Descriptions can be inconsistent when
|
||||
tags are added or removed at the same time.
|
||||
+
|
||||
** `tags[=<bool-value>]`: Instead of only considering annotated tags,
|
||||
`tags[=<bool-value>]`;; Instead of only considering annotated tags,
|
||||
consider lightweight tags as well.
|
||||
** `abbrev=<number>`: Instead of using the default number of hexadecimal digits
|
||||
`abbrev=<number>`;; Instead of using the default number of hexadecimal digits
|
||||
(which will vary according to the number of objects in the repository with a
|
||||
default of 7) of the abbreviated object name, use <number> digits, or as many
|
||||
default of 7) of the abbreviated object name, use _<number>_ digits, or as many
|
||||
digits as needed to form a unique object name.
|
||||
** `match=<pattern>`: Only consider tags matching the given
|
||||
`match=<pattern>`;; Only consider tags matching the given
|
||||
`glob(7)` _<pattern>_, excluding the `refs/tags/` prefix.
|
||||
** `exclude=<pattern>`: Do not consider tags matching the given
|
||||
`exclude=<pattern>`;; Do not consider tags matching the given
|
||||
`glob(7)` _<pattern>_, excluding the `refs/tags/` prefix.
|
||||
|
||||
+%S+:: ref name given on the command line by which the commit was reached
|
||||
@@ -311,7 +336,7 @@ linkgit:git-interpret-trailers[1]. The `trailers` string may be followed by
|
||||
a colon and zero or more comma-separated options. If any option is provided
|
||||
multiple times, the last occurrence wins.
|
||||
+
|
||||
** `key=<key>`: only show trailers with specified <key>. Matching is done
|
||||
`key=<key>`;; only show trailers with specified <key>. Matching is done
|
||||
case-insensitively and trailing colon is optional. If option is
|
||||
given multiple times trailer lines matching any of the keys are
|
||||
shown. This option automatically enables the `only` option so that
|
||||
@@ -319,21 +344,21 @@ multiple times, the last occurrence wins.
|
||||
desired it can be disabled with `only=false`. E.g.,
|
||||
+%(trailers:key=Reviewed-by)+ shows trailer lines with key
|
||||
`Reviewed-by`.
|
||||
** `only[=<bool>]`: select whether non-trailer lines from the trailer
|
||||
`only[=<bool>]`;; select whether non-trailer lines from the trailer
|
||||
block should be included.
|
||||
** `separator=<sep>`: specify the separator inserted between trailer
|
||||
`separator=<sep>`;; specify the separator inserted between trailer
|
||||
lines. Defaults to a line feed character. The string <sep> may contain
|
||||
the literal formatting codes described above. To use comma as
|
||||
separator one must use `%x2C` as it would otherwise be parsed as
|
||||
next option. E.g., +%(trailers:key=Ticket,separator=%x2C )+
|
||||
shows all trailer lines whose key is "Ticket" separated by a comma
|
||||
shows all trailer lines whose key is `Ticket` separated by a comma
|
||||
and a space.
|
||||
** `unfold[=<bool>]`: make it behave as if interpret-trailer's `--unfold`
|
||||
`unfold[=<bool>]`;; make it behave as if interpret-trailer's `--unfold`
|
||||
option was given. E.g.,
|
||||
+%(trailers:only,unfold=true)+ unfolds and shows all trailer lines.
|
||||
** `keyonly[=<bool>]`: only show the key part of the trailer.
|
||||
** `valueonly[=<bool>]`: only show the value part of the trailer.
|
||||
** `key_value_separator=<sep>`: specify the separator inserted between
|
||||
`keyonly[=<bool>]`;; only show the key part of the trailer.
|
||||
`valueonly[=<bool>]`;; only show the value part of the trailer.
|
||||
`key_value_separator=<sep>`;; specify the separator inserted between
|
||||
the key and value of each trailer. Defaults to ": ". Otherwise it
|
||||
shares the same semantics as `separator=<sep>` above.
|
||||
|
||||
@@ -360,9 +385,9 @@ placeholder expands to an empty string.
|
||||
If you add a `' '` (space) after +%+ of a placeholder, a space
|
||||
is inserted immediately before the expansion if and only if the
|
||||
placeholder expands to a non-empty string.
|
||||
--
|
||||
|
||||
* `tformat:`
|
||||
+
|
||||
`tformat:`::
|
||||
The `tformat:` format works exactly like `format:`, except that it
|
||||
provides "terminator" semantics instead of "separator" semantics. In
|
||||
other words, each commit has the message terminator character (usually a
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
* `files` for loose files with packed-refs. This is the default.
|
||||
* `reftable` for the reftable format. This format is experimental and its
|
||||
`files`;; for loose files with packed-refs. This is the default.
|
||||
`reftable`;; for the reftable format. This format is experimental and its
|
||||
internals are subject to change.
|
||||
|
||||
Reference in New Issue
Block a user