mirror of
https://github.com/git/git.git
synced 2024-10-28 04:49:43 +01:00
Merge branch 'ja/doc-synopsis-markup'
The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got vastly pleasant to work with. * ja/doc-synopsis-markup: doc: apply synopsis simplification on git-clone and git-init doc: update the guidelines to reflect the current formatting rules doc: introduce a synopsis typesetting
This commit is contained in:
commit
799450316b
8 changed files with 209 additions and 107 deletions
|
@ -828,78 +828,80 @@ Markup:
|
|||
_<new-branch-name>_
|
||||
_<template-directory>_
|
||||
|
||||
A placeholder is not enclosed in backticks, as it is not a literal.
|
||||
|
||||
When needed, use a distinctive identifier for placeholders, usually
|
||||
made of a qualification and a type:
|
||||
_<git-dir>_
|
||||
_<key-id>_
|
||||
|
||||
When literal and placeholders are mixed, each markup is applied for
|
||||
each sub-entity. If they are stuck, a special markup, called
|
||||
unconstrained formatting is required.
|
||||
Unconstrained formating for placeholders is __<like-this>__
|
||||
Unconstrained formatting for literal formatting is ++like this++
|
||||
`--jobs` _<n>_
|
||||
++--sort=++__<key>__
|
||||
__<directory>__++/.git++
|
||||
++remote.++__<name>__++.mirror++
|
||||
Git's Asciidoc processor has been tailored to treat backticked text
|
||||
as complex synopsis. When literal and placeholders are mixed, you can
|
||||
use the backtick notation which will take care of correctly typesetting
|
||||
the content.
|
||||
`--jobs <n>`
|
||||
`--sort=<key>`
|
||||
`<directory>/.git`
|
||||
`remote.<name>.mirror`
|
||||
`ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
|
||||
|
||||
caveat: ++ unconstrained format is not verbatim and may expand
|
||||
content. Use Asciidoc escapes inside them.
|
||||
As a side effect, backquoted placeholders are correctly typeset, but
|
||||
this style is not recommended.
|
||||
|
||||
Synopsis Syntax
|
||||
|
||||
Syntax grammar is formatted neither as literal nor as placeholder.
|
||||
The synopsis (a paragraph with [synopsis] attribute) is automatically
|
||||
formatted by the toolchain and does not need typesetting.
|
||||
|
||||
A few commented examples follow to provide reference when writing or
|
||||
modifying command usage strings and synopsis sections in the manual
|
||||
pages:
|
||||
|
||||
Possibility of multiple occurrences is indicated by three dots:
|
||||
_<file>_...
|
||||
<file>...
|
||||
(One or more of <file>.)
|
||||
|
||||
Optional parts are enclosed in square brackets:
|
||||
[_<file>_...]
|
||||
[<file>...]
|
||||
(Zero or more of <file>.)
|
||||
|
||||
++--exec-path++[++=++__<path>__]
|
||||
An optional parameter needs to be typeset with unconstrained pairs
|
||||
[<repository>]
|
||||
|
||||
--exec-path[=<path>]
|
||||
(Option with an optional argument. Note that the "=" is inside the
|
||||
brackets.)
|
||||
|
||||
[_<patch>_...]
|
||||
[<patch>...]
|
||||
(Zero or more of <patch>. Note that the dots are inside, not
|
||||
outside the brackets.)
|
||||
|
||||
Multiple alternatives are indicated with vertical bars:
|
||||
[`-q` | `--quiet`]
|
||||
[`--utf8` | `--no-utf8`]
|
||||
[-q | --quiet]
|
||||
[--utf8 | --no-utf8]
|
||||
|
||||
Use spacing around "|" token(s), but not immediately after opening or
|
||||
before closing a [] or () pair:
|
||||
Do: [`-q` | `--quiet`]
|
||||
Don't: [`-q`|`--quiet`]
|
||||
Do: [-q | --quiet]
|
||||
Don't: [-q|--quiet]
|
||||
|
||||
Don't use spacing around "|" tokens when they're used to separate the
|
||||
alternate arguments of an option:
|
||||
Do: ++--track++[++=++(`direct`|`inherit`)]`
|
||||
Don't: ++--track++[++=++(`direct` | `inherit`)]
|
||||
Do: --track[=(direct|inherit)]
|
||||
Don't: --track[=(direct | inherit)]
|
||||
|
||||
Parentheses are used for grouping:
|
||||
[(_<rev>_ | _<range>_)...]
|
||||
[(<rev>|<range>)...]
|
||||
(Any number of either <rev> or <range>. Parens are needed to make
|
||||
it clear that "..." pertains to both <rev> and <range>.)
|
||||
|
||||
[(`-p` _<parent>_)...]
|
||||
[(-p <parent>)...]
|
||||
(Any number of option -p, each with one <parent> argument.)
|
||||
|
||||
`git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
|
||||
git remote set-head <name> (-a|-d|<branch>)
|
||||
(One and only one of "-a", "-d" or "<branch>" _must_ (no square
|
||||
brackets) be provided.)
|
||||
|
||||
And a somewhat more contrived example:
|
||||
`--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
|
||||
--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
|
||||
Here "=" is outside the brackets, because "--diff-filter=" is a
|
||||
valid usage. "*" has its own pair of brackets, because it can
|
||||
(optionally) be specified only when one or more of the letters is
|
||||
|
|
|
@ -28,6 +28,10 @@ ifdef::backend-docbook[]
|
|||
{0#<citerefentry>}
|
||||
{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
|
||||
{0#</citerefentry>}
|
||||
|
||||
[literal-inlinemacro]
|
||||
{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
|
||||
|
||||
endif::backend-docbook[]
|
||||
|
||||
ifdef::backend-docbook[]
|
||||
|
@ -56,4 +60,20 @@ ifdef::backend-xhtml11[]
|
|||
git-relative-html-prefix=
|
||||
[linkgit-inlinemacro]
|
||||
<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
|
||||
|
||||
[literal-inlinemacro]
|
||||
{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
|
||||
|
||||
endif::backend-xhtml11[]
|
||||
|
||||
ifdef::backend-docbook[]
|
||||
ifdef::doctype-manpage[]
|
||||
[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[]
|
||||
[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[]
|
||||
|
|
|
@ -1,5 +1,7 @@
|
|||
require 'asciidoctor'
|
||||
require 'asciidoctor/extensions'
|
||||
require 'asciidoctor/converter/docbook5'
|
||||
require 'asciidoctor/converter/html5'
|
||||
|
||||
module Git
|
||||
module Documentation
|
||||
|
@ -39,10 +41,95 @@ module Git
|
|||
output
|
||||
end
|
||||
end
|
||||
|
||||
class SynopsisBlock < Asciidoctor::Extensions::BlockProcessor
|
||||
|
||||
use_dsl
|
||||
named :synopsis
|
||||
parse_content_as :simple
|
||||
|
||||
def process parent, reader, attrs
|
||||
outlines = reader.lines.map do |l|
|
||||
l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2')
|
||||
.gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$]+)}, '\1{empty}`\2`{empty}')
|
||||
.gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
|
||||
.gsub(']', ']{empty}')
|
||||
end
|
||||
create_block parent, :verse, outlines, attrs
|
||||
end
|
||||
end
|
||||
|
||||
class GitDBConverter < Asciidoctor::Converter::DocBook5Converter
|
||||
|
||||
extend Asciidoctor::Converter::Config
|
||||
register_for 'docbook5'
|
||||
|
||||
def convert_inline_quoted node
|
||||
if (type = node.type) == :asciimath
|
||||
# NOTE fop requires jeuclid to process mathml markup
|
||||
asciimath_available? ? %(<inlineequation>#{(::AsciiMath.parse node.text).to_mathml 'mml:', 'xmlns:mml' => 'http://www.w3.org/1998/Math/MathML'}</inlineequation>) : %(<inlineequation><mathphrase><![CDATA[#{node.text}]]></mathphrase></inlineequation>)
|
||||
elsif type == :latexmath
|
||||
# unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math
|
||||
%(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)
|
||||
elsif type == :monospaced
|
||||
node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2')
|
||||
.gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
|
||||
.gsub(/(<[-a-zA-Z0-9.]+>)/, '<emphasis>\1</emphasis>')
|
||||
else
|
||||
open, close, supports_phrase = QUOTE_TAGS[type]
|
||||
text = node.text
|
||||
if node.role
|
||||
if supports_phrase
|
||||
quoted_text = %(#{open}<phrase role="#{node.role}">#{text}</phrase>#{close})
|
||||
else
|
||||
quoted_text = %(#{open.chop} role="#{node.role}">#{text}#{close})
|
||||
end
|
||||
else
|
||||
quoted_text = %(#{open}#{text}#{close})
|
||||
end
|
||||
node.id ? %(<anchor#{common_attributes node.id, nil, text}/>#{quoted_text}) : quoted_text
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
# register a html5 converter that takes in charge to convert monospaced text into Git style synopsis
|
||||
class GitHTMLConverter < Asciidoctor::Converter::Html5Converter
|
||||
|
||||
extend Asciidoctor::Converter::Config
|
||||
register_for 'html5'
|
||||
|
||||
def convert_inline_quoted node
|
||||
if node.type == :monospaced
|
||||
node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
|
||||
.gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
|
||||
.gsub(/(<[-a-zA-Z0-9.]+>)/, '<em>\1</em>')
|
||||
|
||||
else
|
||||
open, close, tag = QUOTE_TAGS[node.type]
|
||||
if node.id
|
||||
class_attr = node.role ? %( class="#{node.role}") : ''
|
||||
if tag
|
||||
%(#{open.chop} id="#{node.id}"#{class_attr}>#{node.text}#{close})
|
||||
else
|
||||
%(<span id="#{node.id}"#{class_attr}>#{open}#{node.text}#{close}</span>)
|
||||
end
|
||||
elsif node.role
|
||||
if tag
|
||||
%(#{open.chop} class="#{node.role}">#{node.text}#{close})
|
||||
else
|
||||
%(<span class="#{node.role}">#{open}#{node.text}#{close}</span>)
|
||||
end
|
||||
else
|
||||
%(#{open}#{node.text}#{close})
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
Asciidoctor::Extensions.register do
|
||||
inline_macro Git::Documentation::LinkGitProcessor, :linkgit
|
||||
block Git::Documentation::SynopsisBlock
|
||||
postprocessor Git::Documentation::DocumentPostProcessor
|
||||
end
|
||||
|
|
|
@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory
|
|||
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
`git clone` [++--template=++__<template-directory>__]
|
||||
[`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]
|
||||
[`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]
|
||||
[`--dissociate`] [`--separate-git-dir` _<git-dir>_]
|
||||
[`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]
|
||||
[++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++]
|
||||
[`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]
|
||||
[++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_
|
||||
[_<directory>_]
|
||||
[synopsis]
|
||||
git clone [--template=<template-directory>]
|
||||
[-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
|
||||
[-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
|
||||
[--dissociate] [--separate-git-dir <git-dir>]
|
||||
[--depth <depth>] [--[no-]single-branch] [--no-tags]
|
||||
[--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
|
||||
[--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
|
||||
[--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
|
||||
[<directory>]
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
@ -52,7 +52,7 @@ OPTIONS
|
|||
to save space when possible.
|
||||
+
|
||||
If the repository is specified as a local path (e.g., `/path/to/repo`),
|
||||
this is the default, and --local is essentially a no-op. If the
|
||||
this is the default, and `--local` is essentially a no-op. If the
|
||||
repository is specified as a URL, then this flag is ignored (and we
|
||||
never use the local optimizations). Specifying `--no-local` will
|
||||
override the default when `/path/to/repo` is given, using the regular
|
||||
|
@ -64,8 +64,8 @@ prevent the unintentional copying of files by dereferencing the symbolic
|
|||
links.
|
||||
+
|
||||
*NOTE*: this operation can race with concurrent modification to the
|
||||
source repository, similar to running `cp -r src dst` while modifying
|
||||
`src`.
|
||||
source repository, similar to running `cp -r <src> <dst>` while modifying
|
||||
_<src>_.
|
||||
|
||||
`--no-hardlinks`::
|
||||
Force the cloning process from a repository on a local
|
||||
|
@ -101,7 +101,7 @@ 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[-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
|
||||
|
@ -142,17 +142,17 @@ objects from the source repository into a pack in the cloned repository.
|
|||
is specified. This flag forces progress status even if the
|
||||
standard error stream is not directed to a terminal.
|
||||
|
||||
++--server-option=++__<option>__::
|
||||
`--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
|
||||
character. The server's handling of server options, including
|
||||
unknown ones, is server-specific.
|
||||
When multiple ++--server-option=++__<option>__ are given, they are all
|
||||
When multiple `--server-option=<option>` are given, they are all
|
||||
sent to the other side in the order listed on the command line.
|
||||
|
||||
`-n`::
|
||||
`--no-checkout`::
|
||||
No checkout of HEAD is performed after the clone is complete.
|
||||
No checkout of `HEAD` is performed after the clone is complete.
|
||||
|
||||
`--`[`no-`]`reject-shallow`::
|
||||
Fail if the source repository is a shallow repository.
|
||||
|
@ -162,7 +162,7 @@ objects from the source repository into a pack in the cloned repository.
|
|||
`--bare`::
|
||||
Make a 'bare' Git repository. That is, instead of
|
||||
creating _<directory>_ and placing the administrative
|
||||
files in _<directory>_`/.git`, make the _<directory>_
|
||||
files in `<directory>/.git`, make the _<directory>_
|
||||
itself the `$GIT_DIR`. This obviously implies the `--no-checkout`
|
||||
because there is nowhere to check out the working tree.
|
||||
Also the branch heads at the remote are copied directly
|
||||
|
@ -177,13 +177,13 @@ objects from the source repository into a pack in the cloned repository.
|
|||
linkgit:git-sparse-checkout[1] command can be used to grow the
|
||||
working directory as needed.
|
||||
|
||||
++--filter=++__<filter-spec>__::
|
||||
`--filter=<filter-spec>`::
|
||||
Use the partial clone feature and request that the server sends
|
||||
a subset of reachable objects according to a given object filter.
|
||||
When using `--filter`, the supplied _<filter-spec>_ is used for
|
||||
the partial clone filter. For example, `--filter=blob:none` will
|
||||
filter out all blobs (file contents) until needed by Git. Also,
|
||||
++--filter=blob:limit=++__<size>__ will filter out all blobs of size
|
||||
`--filter=blob:limit=<size>` will filter out all blobs of size
|
||||
at least _<size>_. For more details on filter specifications, see
|
||||
the `--filter` option in linkgit:git-rev-list[1].
|
||||
|
||||
|
@ -208,11 +208,11 @@ objects from the source repository into a pack in the cloned repository.
|
|||
|
||||
`-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 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.
|
||||
`--branch` can also take tags and detaches the HEAD at that commit
|
||||
`--branch` can also take tags and detaches the `HEAD` at that commit
|
||||
in the resulting repository.
|
||||
|
||||
`-u` _<upload-pack>_::
|
||||
|
@ -221,12 +221,12 @@ objects from the source repository into a pack in the cloned repository.
|
|||
via ssh, this specifies a non-default path for the command
|
||||
run on the other end.
|
||||
|
||||
++--template=++__<template-directory>__::
|
||||
`--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
|
||||
|
@ -239,25 +239,25 @@ objects from the source repository into a pack in the cloned repository.
|
|||
Due to limitations of the current implementation, some configuration
|
||||
variables do not take effect until after the initial fetch and checkout.
|
||||
Configuration variables known to not take effect are:
|
||||
++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++. Use the
|
||||
`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
|
||||
tips of all branches. If you want to clone submodules shallowly,
|
||||
also pass `--shallow-submodules`.
|
||||
|
||||
++--shallow-since=++__<date>__::
|
||||
`--shallow-since=<date>`::
|
||||
Create a shallow clone with a history after the specified time.
|
||||
|
||||
++--shallow-exclude=++__<revision>__::
|
||||
`--shallow-exclude=<revision>`::
|
||||
Create a shallow clone with a history, excluding commits
|
||||
reachable from a specified remote branch or tag. This option
|
||||
can be specified multiple times.
|
||||
|
||||
`--`[`no-`]`single-branch`::
|
||||
`--[no-]single-branch`::
|
||||
Clone only the history leading to the tip of a single branch,
|
||||
either specified by the `--branch` option or the primary
|
||||
branch remote's `HEAD` points at.
|
||||
|
@ -279,13 +279,13 @@ maintain a branch with no references other than a single cloned
|
|||
branch. This is useful e.g. to maintain minimal clones of the default
|
||||
branch of some repository for search indexing.
|
||||
|
||||
`--recurse-submodules`[`=`{empty}__<pathspec>__]::
|
||||
`--recurse-submodules[=<pathspec>]`::
|
||||
After the clone is created, initialize and clone submodules
|
||||
within based on the provided _<pathspec>_. If no _=<pathspec>_ is
|
||||
within based on the provided _<pathspec>_. If no `=<pathspec>` is
|
||||
provided, all submodules are initialized and cloned.
|
||||
This option can be given multiple times for pathspecs consisting
|
||||
of multiple entries. The resulting clone has `submodule.active` set to
|
||||
the provided pathspec, or "." (meaning all submodules) if no
|
||||
the provided pathspec, or "`.`" (meaning all submodules) if no
|
||||
pathspec is provided.
|
||||
+
|
||||
Submodules are initialized and cloned using their default settings. This is
|
||||
|
@ -295,23 +295,23 @@ the clone is finished. This option is ignored if the cloned repository does
|
|||
not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,
|
||||
or `--mirror` is given)
|
||||
|
||||
`--`[`no-`]`shallow-submodules`::
|
||||
`--[no-]shallow-submodules`::
|
||||
All submodules which are cloned will be shallow with a depth of 1.
|
||||
|
||||
`--`[`no-`]`remote-submodules`::
|
||||
`--[no-]remote-submodules`::
|
||||
All submodules which are cloned will use the status of the submodule's
|
||||
remote-tracking branch to update the submodule, rather than the
|
||||
superproject's recorded SHA-1. Equivalent to passing `--remote` to
|
||||
`git submodule update`.
|
||||
|
||||
`--separate-git-dir=`{empty}__<git-dir>__::
|
||||
`--separate-git-dir=<git-dir>`::
|
||||
Instead of placing the cloned repository where it is supposed
|
||||
to be, place the cloned repository at the specified directory,
|
||||
then make a filesystem-agnostic Git symbolic link to there.
|
||||
The result is Git repository can be separated from working
|
||||
tree.
|
||||
|
||||
`--ref-format=`{empty}__<ref-format>__::
|
||||
`--ref-format=<ref-format>`::
|
||||
|
||||
Specify the given ref storage format for the repository. The valid values are:
|
||||
+
|
||||
|
@ -334,7 +334,7 @@ _<directory>_::
|
|||
for `host.xz:foo/.git`). Cloning into an existing directory
|
||||
is only allowed if the directory is empty.
|
||||
|
||||
`--bundle-uri=`{empty}__<uri>__::
|
||||
`--bundle-uri=<uri>`::
|
||||
Before fetching from the remote, fetch a bundle from the given
|
||||
_<uri>_ and unbundle the data into the local repository. The refs
|
||||
in the bundle will be stored under the hidden `refs/bundle/*`
|
||||
|
|
|
@ -8,12 +8,12 @@ git-init - Create an empty Git repository or reinitialize an existing one
|
|||
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]
|
||||
[`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]
|
||||
[++--ref-format=++__<format>__]
|
||||
[`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]
|
||||
[++--shared++[++=++__<permissions>__]] [_<directory>_]
|
||||
[synopsis]
|
||||
git init [-q | --quiet] [--bare] [--template=<template-directory>]
|
||||
[--separate-git-dir <git-dir>] [--object-format=<format>]
|
||||
[--ref-format=<format>]
|
||||
[-b <branch-name> | --initial-branch=<branch-name>]
|
||||
[--shared[=<permissions>]] [<directory>]
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
|
@ -25,11 +25,11 @@ directory with subdirectories for `objects`, `refs/heads`,
|
|||
commits will be created (see the `--initial-branch` option below
|
||||
for its name).
|
||||
|
||||
If the `$GIT_DIR` environment variable is set then it specifies a path
|
||||
If the `GIT_DIR` environment variable is set then it specifies a path
|
||||
to use instead of `./.git` for the base of the repository.
|
||||
|
||||
If the object storage directory is specified via the
|
||||
`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
|
||||
`GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
|
||||
are created underneath; otherwise, the default `$GIT_DIR/objects`
|
||||
directory is used.
|
||||
|
||||
|
@ -51,26 +51,22 @@ Only print error and warning messages; all other output will be suppressed.
|
|||
Create a bare repository. If `GIT_DIR` environment is not set, it is set to the
|
||||
current working directory.
|
||||
|
||||
++--object-format=++__<format>__::
|
||||
|
||||
`--object-format=<format>`::
|
||||
Specify the given object _<format>_ (hash algorithm) for the repository. The valid
|
||||
values are `sha1` and (if enabled) `sha256`. `sha1` is the default.
|
||||
+
|
||||
include::object-format-disclaimer.txt[]
|
||||
|
||||
++--ref-format=++__<format>__::
|
||||
|
||||
`--ref-format=<format>`::
|
||||
Specify the given ref storage _<format>_ for the repository. The valid values are:
|
||||
+
|
||||
include::ref-storage-format.txt[]
|
||||
|
||||
++--template=++__<template-directory>__::
|
||||
|
||||
`--template=<template-directory>`::
|
||||
Specify the directory from which templates will be used. (See the "TEMPLATE
|
||||
DIRECTORY" section below.)
|
||||
|
||||
++--separate-git-dir=++__<git-dir>__::
|
||||
|
||||
`--separate-git-dir=<git-dir>`::
|
||||
Instead of initializing the repository as a directory to either `$GIT_DIR` or
|
||||
`./.git/`, create a text file there containing the path to the actual
|
||||
repository. This file acts as a filesystem-agnostic Git symbolic link to the
|
||||
|
@ -78,15 +74,14 @@ repository.
|
|||
+
|
||||
If this is a reinitialization, the repository will be moved to the specified path.
|
||||
|
||||
`-b` _<branch-name>_::
|
||||
++--initial-branch=++__<branch-name>__::
|
||||
|
||||
`-b <branch-name>`::
|
||||
`--initial-branch=<branch-name>`::
|
||||
Use _<branch-name>_ for the initial branch in the newly created
|
||||
repository. If not specified, fall back to the default name (currently
|
||||
`master`, but this is subject to change in the future; the name can be
|
||||
customized via the `init.defaultBranch` configuration variable).
|
||||
|
||||
++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::
|
||||
`--shared[=(false|true|umask|group|all|world|everybody|<perm>)]`::
|
||||
|
||||
Specify that the Git repository is to be shared amongst several users. This
|
||||
allows users belonging to the same group to push into that
|
||||
|
|
|
@ -10,19 +10,19 @@ Git supports ssh, git, http, and https protocols (in addition, ftp
|
|||
and ftps can be used for fetching, but this is inefficient and
|
||||
deprecated; do not use them).
|
||||
|
||||
The native transport (i.e. git:// URL) does no authentication and
|
||||
The native transport (i.e. `git://` URL) does no authentication and
|
||||
should be used with caution on unsecured networks.
|
||||
|
||||
The following syntaxes may be used with them:
|
||||
|
||||
- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
|
||||
- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__
|
||||
- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
|
||||
- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
|
||||
- `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
|
||||
- `git://<host>[:<port>]/<path-to-git-repo>`
|
||||
- `http[s]://<host>[:<port>]/<path-to-git-repo>`
|
||||
- `ftp[s]://<host>[:<port>]/<path-to-git-repo>`
|
||||
|
||||
An alternative scp-like syntax may also be used with the ssh protocol:
|
||||
|
||||
- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__
|
||||
- `[<user>@]<host>:/<path-to-git-repo>`
|
||||
|
||||
This syntax is only recognized if there are no slashes before the
|
||||
first colon. This helps differentiate a local path that contains a
|
||||
|
@ -30,17 +30,17 @@ colon. For example the local path `foo:bar` could be specified as an
|
|||
absolute path or `./foo:bar` to avoid being misinterpreted as an ssh
|
||||
url.
|
||||
|
||||
The ssh and git protocols additionally support ++~++__<username>__ expansion:
|
||||
The ssh and git protocols additionally support `~<username>` expansion:
|
||||
|
||||
- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
|
||||
- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
|
||||
- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__
|
||||
- `ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>`
|
||||
- `git://<host>[:<port>]/~<user>/<path-to-git-repo>`
|
||||
- `[<user>@]<host>:~<user>/<path-to-git-repo>`
|
||||
|
||||
For local repositories, also supported by Git natively, the following
|
||||
syntaxes may be used:
|
||||
|
||||
- `/path/to/repo.git/`
|
||||
- ++file:///path/to/repo.git/++
|
||||
- `file:///path/to/repo.git/`
|
||||
|
||||
ifndef::git-clone[]
|
||||
These two syntaxes are mostly equivalent, except when cloning, when
|
||||
|
@ -57,11 +57,11 @@ endif::git-clone[]
|
|||
accept a suitable bundle file. See linkgit:git-bundle[1].
|
||||
|
||||
When Git doesn't know how to handle a certain transport protocol, it
|
||||
attempts to use the `remote-`{empty}__<transport>__ remote helper, if one
|
||||
attempts to use the `remote-<transport>` remote helper, if one
|
||||
exists. To explicitly request a remote helper, the following syntax
|
||||
may be used:
|
||||
|
||||
- _<transport>_::__<address>__
|
||||
- `<transport>::<address>`
|
||||
|
||||
where _<address>_ may be a path, a server and path, or an arbitrary
|
||||
URL-like string recognized by the specific remote helper being
|
||||
|
|
|
@ -119,6 +119,7 @@ Documentation)
|
|||
|
||||
test -n "$ALREADY_HAVE_ASCIIDOCTOR" ||
|
||||
sudo gem install --version 1.5.8 asciidoctor
|
||||
sudo gem install concurrent-ruby
|
||||
;;
|
||||
esac
|
||||
|
||||
|
|
|
@ -56,14 +56,11 @@ txt_to_synopsis () {
|
|||
fi &&
|
||||
b2t="$(builtin_to_txt "$builtin")" &&
|
||||
sed -n \
|
||||
-e '/^\[verse\]$/,/^$/ {
|
||||
-E '/^\[(verse|synopsis)\]$/,/^$/ {
|
||||
/^$/d;
|
||||
/^\[verse\]$/d;
|
||||
s/_//g;
|
||||
s/++//g;
|
||||
s/`//g;
|
||||
s/{litdd}/--/g;
|
||||
s/'\''\(git[ a-z-]*\)'\''/\1/g;
|
||||
/^\[(verse|synopsis)\]$/d;
|
||||
s/\{litdd\}/--/g;
|
||||
s/'\''(git[ a-z-]*)'\''/\1/g;
|
||||
|
||||
p;
|
||||
}' \
|
||||
|
|
Loading…
Reference in a new issue