mirrors/git
1
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-10-28 04:49:43 +01:00
Code Activity

Merge branch 'ja/doc-synopsis-markup'

Browse source 
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:
Junio C Hamano 2024-10-10 14:22:24 -07:00
commit 799450316b
8 changed files with 209 additions and 107 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
Documentation/CodingGuidelines
View file

@ -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

20
Documentation/asciidoc.conf
View file

@ -28,6 +28,10 @@ ifdef::backend-docbook[]
{0#<citerefentry>}
{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
{0#</citerefentry>}
[literal-inlinemacro]
{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-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'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-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!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|&#8230;\\)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<emphasis>\\0</emphasis>!g'"
endif::doctype-manpage[]
endif::backend-docbook[]
ifdef::backend-xhtml11[]
[paradef-default]
synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"
endif::backend-xhtml11[]

87
Documentation/asciidoctor-extensions.rb
View file

@ -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|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
.gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<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|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
.gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<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

78
Documentation/git-clone.txt
View file

@ -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/*`

35
Documentation/git-init.txt
View file

@ -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

26
Documentation/urls.txt
View file

@ -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

1
ci/install-dependencies.sh
View file

@ -119,6 +119,7 @@ Documentation)
test -n "$ALREADY_HAVE_ASCIIDOCTOR" ||
sudo gem install --version 1.5.8 asciidoctor
sudo gem install concurrent-ruby
;;
esac

11
t/t0450-txt-doc-vs-help.sh
View file

@ -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;
}' \