Merge branch 'ma/asciidoctor-more-fixes'

Doc formatting updates.

* ma/asciidoctor-more-fixes:
  gitweb.conf.txt: switch pluses to backticks to help Asciidoctor
  git-merge-index.txt: wrap shell listing in "----"
  git-receive-pack.txt: wrap shell [script] listing in "----"
  git-ls-remote.txt: wrap shell listing in "----"
  Documentation: wrap config listings in "----"
  git-merge-base.txt: render indentations correctly under Asciidoctor
  Documentation: wrap blocks with "--"
This commit is contained in:
Junio C Hamano 2019-10-06 12:25:16 +09:00
commit 314fcd32d7
11 changed files with 211 additions and 172 deletions

View file

@ -178,47 +178,49 @@ to either specify only the realpath version, or both versions.
Example
~~~~~~~
# Core variables
[core]
; Don't trust file modes
filemode = false
----
# Core variables
[core]
; Don't trust file modes
filemode = false
# Our diff algorithm
[diff]
external = /usr/local/bin/diff-wrapper
renames = true
# Our diff algorithm
[diff]
external = /usr/local/bin/diff-wrapper
renames = true
[branch "devel"]
remote = origin
merge = refs/heads/devel
[branch "devel"]
remote = origin
merge = refs/heads/devel
# Proxy settings
[core]
gitProxy="ssh" for "kernel.org"
gitProxy=default-proxy ; for the rest
# Proxy settings
[core]
gitProxy="ssh" for "kernel.org"
gitProxy=default-proxy ; for the rest
[include]
path = /path/to/foo.inc ; include by absolute path
path = foo.inc ; find "foo.inc" relative to the current file
path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory
[include]
path = /path/to/foo.inc ; include by absolute path
path = foo.inc ; find "foo.inc" relative to the current file
path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory
; include if $GIT_DIR is /path/to/foo/.git
[includeIf "gitdir:/path/to/foo/.git"]
path = /path/to/foo.inc
; include if $GIT_DIR is /path/to/foo/.git
[includeIf "gitdir:/path/to/foo/.git"]
path = /path/to/foo.inc
; include for all repositories inside /path/to/group
[includeIf "gitdir:/path/to/group/"]
path = /path/to/foo.inc
; include for all repositories inside /path/to/group
[includeIf "gitdir:/path/to/group/"]
path = /path/to/foo.inc
; include for all repositories inside $HOME/to/group
[includeIf "gitdir:~/to/group/"]
path = /path/to/foo.inc
; include for all repositories inside $HOME/to/group
[includeIf "gitdir:~/to/group/"]
path = /path/to/foo.inc
; relative paths are always relative to the including
; file (if the condition is true); their location is not
; affected by the condition
[includeIf "gitdir:/path/to/group/"]
path = foo.inc
; relative paths are always relative to the including
; file (if the condition is true); their location is not
; affected by the condition
[includeIf "gitdir:/path/to/group/"]
path = foo.inc
----
; include only if we are in a worktree where foo-branch is
; currently checked out

View file

@ -282,18 +282,20 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].)
--untracked-files[=<mode>]::
Show untracked files.
+
--
The mode parameter is optional (defaults to 'all'), and is used to
specify the handling of untracked files; when -u is not used, the
default is 'normal', i.e. show untracked files and directories.
+
The possible options are:
+
- 'no' - Show no untracked files
- 'normal' - Shows untracked files and directories
- 'all' - Also shows individual files in untracked directories.
+
The default can be changed using the status.showUntrackedFiles
configuration variable documented in linkgit:git-config[1].
--
-v::
--verbose::

View file

@ -339,33 +339,35 @@ EXAMPLES
Given a .git/config like this:
#
# This is the config file, and
# a '#' or ';' character indicates
# a comment
#
------------
#
# This is the config file, and
# a '#' or ';' character indicates
# a comment
#
; core variables
[core]
; Don't trust file modes
filemode = false
; core variables
[core]
; Don't trust file modes
filemode = false
; Our diff algorithm
[diff]
external = /usr/local/bin/diff-wrapper
renames = true
; Our diff algorithm
[diff]
external = /usr/local/bin/diff-wrapper
renames = true
; Proxy settings
[core]
gitproxy=proxy-command for kernel.org
gitproxy=default-proxy ; for all the rest
; Proxy settings
[core]
gitproxy=proxy-command for kernel.org
gitproxy=default-proxy ; for all the rest
; HTTP
[http]
sslVerify
[http "https://weak.example.com"]
sslVerify = false
cookieFile = /tmp/cookie.txt
; HTTP
[http]
sslVerify
[http "https://weak.example.com"]
sslVerify = false
cookieFile = /tmp/cookie.txt
------------
you can set the filemode to true with

View file

@ -92,21 +92,23 @@ OPTIONS
EXAMPLES
--------
$ git ls-remote --tags ./.
d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99
f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1
7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3
c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2
0918385dbd9656cab0d1d81ba7453d49bbc16250 refs/tags/junio-gpg-pub
$ git ls-remote http://www.kernel.org/pub/scm/git/git.git master pu rc
5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master
c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/pu
$ git remote add korg http://www.kernel.org/pub/scm/git/git.git
$ git ls-remote --tags korg v\*
d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99
f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1
c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2
7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3
----
$ git ls-remote --tags ./.
d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99
f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1
7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3
c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2
0918385dbd9656cab0d1d81ba7453d49bbc16250 refs/tags/junio-gpg-pub
$ git ls-remote http://www.kernel.org/pub/scm/git/git.git master pu rc
5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master
c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/pu
$ git remote add korg http://www.kernel.org/pub/scm/git/git.git
$ git ls-remote --tags korg v\*
d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99
f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1
c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2
7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3
----
SEE ALSO
--------

View file

@ -80,9 +80,11 @@ which is reachable from both 'A' and 'B' through the parent relationship.
For example, with this topology:
o---o---o---B
/
---o---1---o---o---o---A
....
o---o---o---B
/
---o---1---o---o---o---A
....
the merge base between 'A' and 'B' is '1'.
@ -90,21 +92,25 @@ Given three commits 'A', 'B' and 'C', `git merge-base A B C` will compute the
merge base between 'A' and a hypothetical commit 'M', which is a merge
between 'B' and 'C'. For example, with this topology:
o---o---o---o---C
/
/ o---o---o---B
/ /
---2---1---o---o---o---A
....
o---o---o---o---C
/
/ o---o---o---B
/ /
---2---1---o---o---o---A
....
the result of `git merge-base A B C` is '1'. This is because the
equivalent topology with a merge commit 'M' between 'B' and 'C' is:
o---o---o---o---o
/ \
/ o---o---o---o---M
/ /
---2---1---o---o---o---A
....
o---o---o---o---o
/ \
/ o---o---o---o---M
/ /
---2---1---o---o---o---A
....
and the result of `git merge-base A M` is '1'. Commit '2' is also a
common ancestor between 'A' and 'M', but '1' is a better common ancestor,
@ -116,11 +122,13 @@ the best common ancestor of all commits.
When the history involves criss-cross merges, there can be more than one
'best' common ancestor for two commits. For example, with this topology:
---1---o---A
\ /
X
/ \
---2---o---o---B
....
---1---o---A
\ /
X
/ \
---2---o---o---B
....
both '1' and '2' are merge-bases of A and B. Neither one is better than
the other (both are 'best' merge bases). When the `--all` option is not given,
@ -131,18 +139,22 @@ and B is (or at least used to be) to compute the merge base between
A and B, and check if it is the same as A, in which case, A is an
ancestor of B. You will see this idiom used often in older scripts.
A=$(git rev-parse --verify A)
if test "$A" = "$(git merge-base A B)"
then
... A is an ancestor of B ...
fi
....
A=$(git rev-parse --verify A)
if test "$A" = "$(git merge-base A B)"
then
... A is an ancestor of B ...
fi
....
In modern git, you can say this in a more direct way:
if git merge-base --is-ancestor A B
then
... A is an ancestor of B ...
fi
....
if git merge-base --is-ancestor A B
then
... A is an ancestor of B ...
fi
....
instead.
@ -154,13 +166,15 @@ topic origin/master`, the history of remote-tracking branch
`origin/master` may have been rewound and rebuilt, leading to a
history of this shape:
o---B2
/
---o---o---B1--o---o---o---B (origin/master)
\
B0
\
D0---D1---D (topic)
....
o---B2
/
---o---o---B1--o---o---o---B (origin/master)
\
B0
\
D0---D1---D (topic)
....
where `origin/master` used to point at commits B0, B1, B2 and now it
points at B, and your `topic` branch was started on top of it back
@ -193,13 +207,15 @@ will find B0, and
will replay D0, D1 and D on top of B to create a new history of this
shape:
o---B2
/
---o---o---B1--o---o---o---B (origin/master)
\ \
B0 D0'--D1'--D' (topic - updated)
\
D0---D1---D (topic - old)
....
o---B2
/
---o---o---B1--o---o---o---B (origin/master)
\ \
B0 D0'--D1'--D' (topic - updated)
\
D0---D1---D (topic - old)
....
A caveat is that older reflog entries in your repository may be
expired by `git gc`. If B0 no longer appears in the reflog of the

View file

@ -54,20 +54,24 @@ original is first. But the argument order to the 3-way merge program
Examples:
torvalds@ppc970:~/merge-test> git merge-index cat MM
This is MM from the original tree. # original
This is modified MM in the branch A. # merge1
This is modified MM in the branch B. # merge2
This is modified MM in the branch B. # current contents
----
torvalds@ppc970:~/merge-test> git merge-index cat MM
This is MM from the original tree. # original
This is modified MM in the branch A. # merge1
This is modified MM in the branch B. # merge2
This is modified MM in the branch B. # current contents
----
or
torvalds@ppc970:~/merge-test> git merge-index cat AA MM
cat: : No such file or directory
This is added AA in the branch A.
This is added AA in the branch B.
This is added AA in the branch B.
fatal: merge program failed
----
torvalds@ppc970:~/merge-test> git merge-index cat AA MM
cat: : No such file or directory
This is added AA in the branch A.
This is added AA in the branch B.
This is added AA in the branch B.
fatal: merge program failed
----
where the latter example shows how 'git merge-index' will stop trying to
merge once anything has returned an error (i.e., `cat` returned an error

View file

@ -165,29 +165,31 @@ ref listing the commits pushed to the repository, and logs the push
certificates of signed pushes with good signatures to a logger
service:
#!/bin/sh
# mail out commit update information.
while read oval nval ref
do
if expr "$oval" : '0*$' >/dev/null
then
echo "Created a new ref, with the following commits:"
git rev-list --pretty "$nval"
else
echo "New commits:"
git rev-list --pretty "$nval" "^$oval"
fi |
mail -s "Changes to ref $ref" commit-list@mydomain
done
# log signed push certificate, if any
if test -n "${GIT_PUSH_CERT-}" && test ${GIT_PUSH_CERT_STATUS} = G
----
#!/bin/sh
# mail out commit update information.
while read oval nval ref
do
if expr "$oval" : '0*$' >/dev/null
then
(
echo expected nonce is ${GIT_PUSH_NONCE}
git cat-file blob ${GIT_PUSH_CERT}
) | mail -s "push certificate from $GIT_PUSH_CERT_SIGNER" push-log@mydomain
fi
exit 0
echo "Created a new ref, with the following commits:"
git rev-list --pretty "$nval"
else
echo "New commits:"
git rev-list --pretty "$nval" "^$oval"
fi |
mail -s "Changes to ref $ref" commit-list@mydomain
done
# log signed push certificate, if any
if test -n "${GIT_PUSH_CERT-}" && test ${GIT_PUSH_CERT_STATUS} = G
then
(
echo expected nonce is ${GIT_PUSH_NONCE}
git cat-file blob ${GIT_PUSH_CERT}
) | mail -s "push certificate from $GIT_PUSH_CERT_SIGNER" push-log@mydomain
fi
exit 0
----
The exit code from this hook invocation is ignored, however a
non-zero exit code will generate an error message.
@ -212,8 +214,10 @@ anyway.
This hook can be used, for example, to run `git update-server-info`
if the repository is packed and is served via a dumb transport.
#!/bin/sh
exec git update-server-info
----
#!/bin/sh
exec git update-server-info
----
QUARANTINE ENVIRONMENT

View file

@ -486,11 +486,13 @@ Use gmail as the smtp server
To use 'git send-email' to send your patches through the GMail SMTP server,
edit ~/.gitconfig to specify your account settings:
[sendemail]
smtpEncryption = tls
smtpServer = smtp.gmail.com
smtpUser = yourname@gmail.com
smtpServerPort = 587
----
[sendemail]
smtpEncryption = tls
smtpServer = smtp.gmail.com
smtpUser = yourname@gmail.com
smtpServerPort = 587
----
If you have multifactor authentication setup on your gmail account, you will
need to generate an app-specific password for use with 'git send-email'. Visit

View file

@ -59,16 +59,17 @@ This is optional and defaults to the original version 'v1' format.
--untracked-files[=<mode>]::
Show untracked files.
+
--
The mode parameter is used to specify the handling of untracked files.
It is optional: it defaults to 'all', and if specified, it must be
stuck to the option (e.g. `-uno`, but not `-u no`).
+
The possible options are:
+
- 'no' - Show no untracked files.
- 'normal' - Shows untracked files and directories.
- 'all' - Also shows individual files in untracked directories.
+
When `-u` option is not used, untracked files and directories are
shown (i.e. the same as specifying `normal`), to help you avoid
forgetting to add newly created files. Because it takes extra work
@ -78,9 +79,10 @@ Consider enabling untracked cache and split index if supported (see
`git update-index --untracked-cache` and `git update-index
--split-index`), Otherwise you can use `no` to have `git status`
return more quickly without showing untracked files.
+
The default can be changed using the status.showUntrackedFiles
configuration variable documented in linkgit:git-config[1].
--
--ignore-submodules[=<when>]::
Ignore changes to submodules when looking for changes. <when> can be
@ -100,11 +102,12 @@ configuration variable documented in linkgit:git-config[1].
--ignored[=<mode>]::
Show ignored files as well.
+
--
The mode parameter is used to specify the handling of ignored files.
It is optional: it defaults to 'traditional'.
+
The possible options are:
+
- 'traditional' - Shows ignored files and directories, unless
--untracked-files=all is specified, in which case
individual files in ignored directories are
@ -112,12 +115,13 @@ The possible options are:
- 'no' - Show no ignored files.
- 'matching' - Shows ignored files and directories matching an
ignore pattern.
+
When 'matching' mode is specified, paths that explicitly match an
ignored pattern are shown. If a directory matches an ignore pattern,
then it is shown, but not paths contained in the ignored directory. If
a directory does not match an ignore pattern, but all contents are
ignored, then the directory is not shown, but all contents are shown.
--
-z::
Terminate entries with NUL, instead of LF. This implies

View file

@ -105,14 +105,15 @@ EXAMPLES
Consider the following .gitmodules file:
[submodule "libfoo"]
path = include/foo
url = git://foo.com/git/lib.git
[submodule "libbar"]
path = include/bar
url = git://bar.com/git/lib.git
----
[submodule "libfoo"]
path = include/foo
url = git://foo.com/git/lib.git
[submodule "libbar"]
path = include/bar
url = git://bar.com/git/lib.git
----
This defines two submodules, `libfoo` and `libbar`. These are expected to
be checked out in the paths `include/foo` and `include/bar`, and for both

View file

@ -786,9 +786,9 @@ forks::
subdirectories of project root (basename) to be forks of existing
projects. For each project +$projname.git+, projects in the
+$projname/+ directory and its subdirectories will not be
shown in the main projects list. Instead, a \'\+' mark is shown
next to +$projname+, which links to a "forks" view that lists all
the forks (all projects in +$projname/+ subdirectory). Additionally
shown in the main projects list. Instead, a \'+' mark is shown
next to `$projname`, which links to a "forks" view that lists all
the forks (all projects in `$projname/` subdirectory). Additionally
a "forks" view for a project is linked from project summary page.
+
If the project list is taken from a file (+$projects_list+ points to a