kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

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
maint
Junio C Hamano 2024-10-10 14:22:24 -07:00
parent 777489f9e0 22293895c0
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>_ _<new-branch-name>_
_<template-directory>_ _<template-directory>_


A placeholder is not enclosed in backticks, as it is not a literal.

When needed, use a distinctive identifier for placeholders, usually When needed, use a distinctive identifier for placeholders, usually
made of a qualification and a type: made of a qualification and a type:
_<git-dir>_ _<git-dir>_
_<key-id>_ _<key-id>_


When literal and placeholders are mixed, each markup is applied for Git's Asciidoc processor has been tailored to treat backticked text
each sub-entity. If they are stuck, a special markup, called as complex synopsis. When literal and placeholders are mixed, you can
unconstrained formatting is required. use the backtick notation which will take care of correctly typesetting
Unconstrained formating for placeholders is __<like-this>__ the content.
Unconstrained formatting for literal formatting is ++like this++ `--jobs <n>`
`--jobs` _<n>_ `--sort=<key>`
++--sort=++__<key>__ `<directory>/.git`
__<directory>__++/.git++ `remote.<name>.mirror`
++remote.++__<name>__++.mirror++ `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`


caveat: ++ unconstrained format is not verbatim and may expand As a side effect, backquoted placeholders are correctly typeset, but
content. Use Asciidoc escapes inside them. this style is not recommended.


Synopsis Syntax 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 A few commented examples follow to provide reference when writing or
modifying command usage strings and synopsis sections in the manual modifying command usage strings and synopsis sections in the manual
pages: pages:


Possibility of multiple occurrences is indicated by three dots: Possibility of multiple occurrences is indicated by three dots:
_<file>_... <file>...
(One or more of <file>.) (One or more of <file>.)


Optional parts are enclosed in square brackets: Optional parts are enclosed in square brackets:
[_<file>_...] [<file>...]
(Zero or more of <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 (Option with an optional argument. Note that the "=" is inside the
brackets.) brackets.)


[_<patch>_...] [<patch>...]
(Zero or more of <patch>. Note that the dots are inside, not (Zero or more of <patch>. Note that the dots are inside, not
outside the brackets.) outside the brackets.)


Multiple alternatives are indicated with vertical bars: Multiple alternatives are indicated with vertical bars:
[`-q` | `--quiet`] [-q | --quiet]
[`--utf8` | `--no-utf8`] [--utf8 | --no-utf8]


Use spacing around "|" token(s), but not immediately after opening or Use spacing around "|" token(s), but not immediately after opening or
before closing a [] or () pair: before closing a [] or () pair:
Do: [`-q` | `--quiet`] Do: [-q | --quiet]
Don't: [`-q`|`--quiet`] Don't: [-q|--quiet]


Don't use spacing around "|" tokens when they're used to separate the Don't use spacing around "|" tokens when they're used to separate the
alternate arguments of an option: alternate arguments of an option:
Do: ++--track++[++=++(`direct`|`inherit`)]` Do: --track[=(direct|inherit)]
Don't: ++--track++[++=++(`direct` | `inherit`)] Don't: --track[=(direct | inherit)]


Parentheses are used for grouping: Parentheses are used for grouping:
[(_<rev>_ | _<range>_)...] [(<rev>|<range>)...]
(Any number of either <rev> or <range>. Parens are needed to make (Any number of either <rev> or <range>. Parens are needed to make
it clear that "..." pertains to both <rev> and <range>.) it clear that "..." pertains to both <rev> and <range>.)


[(`-p` _<parent>_)...] [(-p <parent>)...]
(Any number of option -p, each with one <parent> argument.) (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 (One and only one of "-a", "-d" or "<branch>" _must_ (no square
brackets) be provided.) brackets) be provided.)


And a somewhat more contrived example: 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 Here "=" is outside the brackets, because "--diff-filter=" is a
valid usage. "*" has its own pair of brackets, because it can valid usage. "*" has its own pair of brackets, because it can
(optionally) be specified only when one or more of the letters is (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#<citerefentry>}
{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>} {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
{0#</citerefentry>} {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[] endif::backend-docbook[]


ifdef::backend-docbook[] ifdef::backend-docbook[]
@ -56,4 +60,20 @@ ifdef::backend-xhtml11[]
git-relative-html-prefix= git-relative-html-prefix=
[linkgit-inlinemacro] [linkgit-inlinemacro]
<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a> <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[] endif::backend-xhtml11[]

87
Documentation/asciidoctor-extensions.rb
View File

@ -1,5 +1,7 @@
require 'asciidoctor' require 'asciidoctor'
require 'asciidoctor/extensions' require 'asciidoctor/extensions'
require 'asciidoctor/converter/docbook5'
require 'asciidoctor/converter/html5'


module Git module Git
module Documentation module Documentation
@ -39,10 +41,95 @@ module Git
output output
end end
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
end end


Asciidoctor::Extensions.register do Asciidoctor::Extensions.register do
inline_macro Git::Documentation::LinkGitProcessor, :linkgit inline_macro Git::Documentation::LinkGitProcessor, :linkgit
block Git::Documentation::SynopsisBlock
postprocessor Git::Documentation::DocumentPostProcessor postprocessor Git::Documentation::DocumentPostProcessor
end end

78
Documentation/git-clone.txt
View File

@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory


SYNOPSIS SYNOPSIS
-------- --------
[verse] [synopsis]
`git clone` [++--template=++__<template-directory>__] git clone [--template=<template-directory>]
[`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`] [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
[`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_] [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
[`--dissociate`] [`--separate-git-dir` _<git-dir>_] [--dissociate] [--separate-git-dir <git-dir>]
[`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`] [--depth <depth>] [--[no-]single-branch] [--no-tags]
[++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++] [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
[`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`] [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
[++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_ [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
[_<directory>_] [<directory>]


DESCRIPTION DESCRIPTION
----------- -----------
@ -52,7 +52,7 @@ OPTIONS
to save space when possible. to save space when possible.
+ +
If the repository is specified as a local path (e.g., `/path/to/repo`), 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 repository is specified as a URL, then this flag is ignored (and we
never use the local optimizations). Specifying `--no-local` will never use the local optimizations). Specifying `--no-local` will
override the default when `/path/to/repo` is given, using the regular 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. links.
+ +
*NOTE*: this operation can race with concurrent modification to the *NOTE*: this operation can race with concurrent modification to the
source repository, similar to running `cp -r src dst` while modifying source repository, similar to running `cp -r <src> <dst>` while modifying
`src`. _<src>_.


`--no-hardlinks`:: `--no-hardlinks`::
Force the cloning process from a repository on a local 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 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. 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, If the reference _<repository>_ is on the local machine,
automatically setup `.git/objects/info/alternates` to automatically setup `.git/objects/info/alternates` to
obtain objects from the reference _<repository>_. Using 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 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.


++--server-option=++__<option>__:: `--server-option=<option>`::
Transmit the given string to the server when communicating using 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 character. The server's handling of server options, including
unknown ones, is server-specific. 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. sent to the other side in the order listed on the command line.


`-n`:: `-n`::
`--no-checkout`:: `--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`:: `--`[`no-`]`reject-shallow`::
Fail if the source repository is a shallow repository. 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`:: `--bare`::
Make a 'bare' Git repository. That is, instead of Make a 'bare' Git repository. That is, instead of
creating _<directory>_ and placing the administrative 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` itself the `$GIT_DIR`. This obviously implies the `--no-checkout`
because there is nowhere to check out the working tree. because there is nowhere to check out the working tree.
Also the branch heads at the remote are copied directly 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 linkgit:git-sparse-checkout[1] command can be used to grow the
working directory as needed. working directory as needed.


++--filter=++__<filter-spec>__:: `--filter=<filter-spec>`::
Use the partial clone feature and request that the server sends Use the partial clone feature and request that the server sends
a subset of reachable objects according to a given object filter. a subset of reachable objects according to a given object filter.
When using `--filter`, the supplied _<filter-spec>_ is used for When using `--filter`, the supplied _<filter-spec>_ is used for
the partial clone filter. For example, `--filter=blob:none` will the partial clone filter. For example, `--filter=blob:none` will
filter out all blobs (file contents) until needed by Git. Also, 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 at least _<size>_. For more details on filter specifications, see
the `--filter` option in linkgit:git-rev-list[1]. 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>_:: `-b` _<name>_::
`--branch` _<name>_:: `--branch` _<name>_::
Instead of pointing the newly created HEAD to the branch pointed Instead of pointing the newly created `HEAD` to the branch pointed
to by the cloned repository's HEAD, point to _<name>_ branch to by the cloned repository's `HEAD`, point to _<name>_ branch
instead. In a non-bare repository, this is the branch that will instead. In a non-bare repository, this is the branch that will
be checked out. 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. in the resulting repository.


`-u` _<upload-pack>_:: `-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 via ssh, this specifies a non-default path for the command
run on the other end. run on the other end.


++--template=++__<template-directory>__:: `--template=<template-directory>`::
Specify the directory from which templates will be used; Specify the directory from which templates will be used;
(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)


`-c` __<key>__++=++__<value>__:: `-c` `<key>=<value>`::
`--config` __<key>__++=++__<value>__:: `--config` `<key>=<value>`::
Set a configuration variable in the newly-created repository; Set a configuration variable in the newly-created repository;
this takes effect immediately after the repository is this takes effect immediately after the repository is
initialized, but before the remote history is fetched or any 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 Due to limitations of the current implementation, some configuration
variables do not take effect until after the initial fetch and checkout. variables do not take effect until after the initial fetch and checkout.
Configuration variables known to not take effect are: 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. corresponding `--mirror` and `--no-tags` options instead.


`--depth` _<depth>_:: `--depth <depth>`::
Create a 'shallow' clone with a history truncated to the Create a 'shallow' clone with a history truncated to the
specified number of commits. Implies `--single-branch` unless specified number of commits. Implies `--single-branch` unless
`--no-single-branch` is given to fetch the histories near the `--no-single-branch` is given to fetch the histories near the
tips of all branches. If you want to clone submodules shallowly, tips of all branches. If you want to clone submodules shallowly,
also pass `--shallow-submodules`. also pass `--shallow-submodules`.


++--shallow-since=++__<date>__:: `--shallow-since=<date>`::
Create a shallow clone with a history after the specified time. 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 Create a shallow clone with a history, excluding commits
reachable from a specified remote branch or tag. This option reachable from a specified remote branch or tag. This option
can be specified multiple times. can be specified multiple times.


`--`[`no-`]`single-branch`:: `--[no-]single-branch`::
Clone only the history leading to the tip of a single branch, Clone only the history leading to the tip of a single branch,
either specified by the `--branch` option or the primary either specified by the `--branch` option or the primary
branch remote's `HEAD` points at. 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. This is useful e.g. to maintain minimal clones of the default
branch of some repository for search indexing. branch of some repository for search indexing.


`--recurse-submodules`[`=`{empty}__<pathspec>__]:: `--recurse-submodules[=<pathspec>]`::
After the clone is created, initialize and clone submodules 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. provided, all submodules are initialized and cloned.
This option can be given multiple times for pathspecs consisting This option can be given multiple times for pathspecs consisting
of multiple entries. The resulting clone has `submodule.active` set to 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. pathspec is provided.
+ +
Submodules are initialized and cloned using their default settings. This is 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`, not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,
or `--mirror` is given) or `--mirror` is given)


`--`[`no-`]`shallow-submodules`:: `--[no-]shallow-submodules`::
All submodules which are cloned will be shallow with a depth of 1. 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 All submodules which are cloned will use the status of the submodule's
remote-tracking branch to update the submodule, rather than the remote-tracking branch to update the submodule, rather than the
superproject's recorded SHA-1. Equivalent to passing `--remote` to superproject's recorded SHA-1. Equivalent to passing `--remote` to
`git submodule update`. `git submodule update`.


`--separate-git-dir=`{empty}__<git-dir>__:: `--separate-git-dir=<git-dir>`::
Instead of placing the cloned repository where it is supposed Instead of placing the cloned repository where it is supposed
to be, place the cloned repository at the specified directory, to be, place the cloned repository at the specified directory,
then make a filesystem-agnostic Git symbolic link to there. then make a filesystem-agnostic Git symbolic link to there.
The result is Git repository can be separated from working The result is Git repository can be separated from working
tree. tree.


`--ref-format=`{empty}__<ref-format>__:: `--ref-format=<ref-format>`::


Specify the given ref storage format for the repository. The valid values are: 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 for `host.xz:foo/.git`). Cloning into an existing directory
is only allowed if the directory is empty. 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 Before fetching from the remote, fetch a bundle from the given
_<uri>_ and unbundle the data into the local repository. The refs _<uri>_ and unbundle the data into the local repository. The refs
in the bundle will be stored under the hidden `refs/bundle/*` 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 SYNOPSIS
-------- --------
[verse] [synopsis]
`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__] git init [-q | --quiet] [--bare] [--template=<template-directory>]
[`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__] [--separate-git-dir <git-dir>] [--object-format=<format>]
[++--ref-format=++__<format>__] [--ref-format=<format>]
[`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__] [-b <branch-name> | --initial-branch=<branch-name>]
[++--shared++[++=++__<permissions>__]] [_<directory>_] [--shared[=<permissions>]] [<directory>]




DESCRIPTION DESCRIPTION
@ -25,11 +25,11 @@ directory with subdirectories for `objects`, `refs/heads`,
commits will be created (see the `--initial-branch` option below commits will be created (see the `--initial-branch` option below
for its name). 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. to use instead of `./.git` for the base of the repository.


If the object storage directory is specified via the 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` are created underneath; otherwise, the default `$GIT_DIR/objects`
directory is used. 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 Create a bare repository. If `GIT_DIR` environment is not set, it is set to the
current working directory. current working directory.


++--object-format=++__<format>__:: `--object-format=<format>`::

Specify the given object _<format>_ (hash algorithm) for the repository. The valid Specify the given object _<format>_ (hash algorithm) for the repository. The valid
values are `sha1` and (if enabled) `sha256`. `sha1` is the default. values are `sha1` and (if enabled) `sha256`. `sha1` is the default.
+ +
include::object-format-disclaimer.txt[] include::object-format-disclaimer.txt[]


++--ref-format=++__<format>__:: `--ref-format=<format>`::

Specify the given ref storage _<format>_ for the repository. The valid values are: Specify the given ref storage _<format>_ for the repository. The valid values are:
+ +
include::ref-storage-format.txt[] include::ref-storage-format.txt[]


++--template=++__<template-directory>__:: `--template=<template-directory>`::

Specify the directory from which templates will be used. (See the "TEMPLATE Specify the directory from which templates will be used. (See the "TEMPLATE
DIRECTORY" section below.) 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 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 `./.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 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. If this is a reinitialization, the repository will be moved to the specified path.


`-b` _<branch-name>_:: `-b <branch-name>`::
++--initial-branch=++__<branch-name>__:: `--initial-branch=<branch-name>`::

Use _<branch-name>_ for the initial branch in the newly created Use _<branch-name>_ for the initial branch in the newly created
repository. If not specified, fall back to the default name (currently 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 `master`, but this is subject to change in the future; the name can be
customized via the `init.defaultBranch` configuration variable). 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 Specify that the Git repository is to be shared amongst several users. This
allows users belonging to the same group to push into that 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 and ftps can be used for fetching, but this is inefficient and
deprecated; do not use them). 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. should be used with caution on unsecured networks.


The following syntaxes may be used with them: The following syntaxes may be used with them:


- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__ - `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__ - `git://<host>[:<port>]/<path-to-git-repo>`
- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__ - `http[s]://<host>[:<port>]/<path-to-git-repo>`
- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<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: 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 This syntax is only recognized if there are no slashes before the
first colon. This helps differentiate a local path that contains a 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 absolute path or `./foo:bar` to avoid being misinterpreted as an ssh
url. 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>__ - `ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>`
- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__ - `git://<host>[:<port>]/~<user>/<path-to-git-repo>`
- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__ - `[<user>@]<host>:~<user>/<path-to-git-repo>`


For local repositories, also supported by Git natively, the following For local repositories, also supported by Git natively, the following
syntaxes may be used: syntaxes may be used:


- `/path/to/repo.git/` - `/path/to/repo.git/`
- ++file:///path/to/repo.git/++ - `file:///path/to/repo.git/`


ifndef::git-clone[] ifndef::git-clone[]
These two syntaxes are mostly equivalent, except when cloning, when 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]. accept a suitable bundle file. See linkgit:git-bundle[1].


When Git doesn't know how to handle a certain transport protocol, it 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 exists. To explicitly request a remote helper, the following syntax
may be used: may be used:


- _<transport>_::__<address>__ - `<transport>::<address>`


where _<address>_ may be a path, a server and path, or an arbitrary where _<address>_ may be a path, a server and path, or an arbitrary
URL-like string recognized by the specific remote helper being 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" || test -n "$ALREADY_HAVE_ASCIIDOCTOR" ||
sudo gem install --version 1.5.8 asciidoctor sudo gem install --version 1.5.8 asciidoctor
sudo gem install concurrent-ruby
;; ;;
esac esac



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

@ -56,14 +56,11 @@ txt_to_synopsis () {
fi && fi &&
b2t="$(builtin_to_txt "$builtin")" && b2t="$(builtin_to_txt "$builtin")" &&
sed -n \ sed -n \
-e '/^\[verse\]$/,/^$/ { -E '/^\[(verse|synopsis)\]$/,/^$/ {
/^$/d; /^$/d;
/^\[verse\]$/d; /^\[(verse|synopsis)\]$/d;
s/_//g; s/\{litdd\}/--/g;
s/++//g; s/'\''(git[ a-z-]*)'\''/\1/g;
s/`//g;
s/{litdd}/--/g;
s/'\''\(git[ a-z-]*\)'\''/\1/g;


p; p;
}' \ }' \