Merge branch 'ah/doc-updates' into maint
Doc updates.
* ah/doc-updates:
doc: fix formatting in git-update-ref
doc: fix indentation of listing blocks in gitweb.conf.txt
doc: fix descripion for 'git tag --format'
doc: fix inappropriate monospace formatting
doc: fix ASCII art tab spacing
doc: clarify boundaries of 'git worktree list --porcelain'
diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt
index 0f9ef2f..e999251 100644
--- a/Documentation/git-bisect-lk2009.txt
+++ b/Documentation/git-bisect-lk2009.txt
@@ -633,11 +633,11 @@
Let's take the following graph as an example:
-------------
- G-H-I-J
- / \
+ G-H-I-J
+ / \
A-B-C-D-E-F O
- \ /
- K-L-M-N
+ \ /
+ K-L-M-N
-------------
If we compute the following non optimal function on it:
@@ -649,25 +649,25 @@
we get:
-------------
- 4 3 2 1
- G-H-I-J
+ 4 3 2 1
+ G-H-I-J
1 2 3 4 5 6/ \0
A-B-C-D-E-F O
- \ /
- K-L-M-N
- 4 3 2 1
+ \ /
+ K-L-M-N
+ 4 3 2 1
-------------
but with the algorithm used by git bisect we get:
-------------
- 7 7 6 5
- G-H-I-J
+ 7 7 6 5
+ G-H-I-J
1 2 3 4 5 6/ \0
A-B-C-D-E-F O
- \ /
- K-L-M-N
- 7 7 6 5
+ \ /
+ K-L-M-N
+ 7 7 6 5
-------------
So we chose G, H, K or L as the best bisection point, which is better
@@ -773,7 +773,7 @@
-------------
A-B-C-D-E-F-G <--main
\
- H-I-J <--dev
+ H-I-J <--dev
-------------
The commit "D" is called a "merge base" for branch "main" and "dev"
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 9db0292..801de2f 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -311,9 +311,9 @@
commits, one of them tagged, and with branch 'master' checked out:
------------
- HEAD (refers to branch 'master')
- |
- v
+ HEAD (refers to branch 'master')
+ |
+ v
a---b---c branch 'master' (refers to commit 'c')
^
|
@@ -329,9 +329,9 @@
------------
$ edit; git add; git commit
- HEAD (refers to branch 'master')
- |
- v
+ HEAD (refers to branch 'master')
+ |
+ v
a---b---c---d branch 'master' (refers to commit 'd')
^
|
@@ -398,7 +398,7 @@
------------
$ git checkout master
- HEAD (refers to branch 'master')
+ HEAD (refers to branch 'master')
e---f |
/ v
a---b---c---d branch 'master' (refers to commit 'd')
diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index 502e00e..9f07f4f 100644
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -154,13 +154,13 @@
`origin/master` may have been rewound and rebuilt, leading to a
history of this shape:
- o---B2
+ o---B2
/
---o---o---B1--o---o---o---B (origin/master)
\
- B0
+ B0
\
- D0---D1---D (topic)
+ 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
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 92f9c12..f2d644e 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -187,6 +187,12 @@
`--create-reflog`, but currently does not negate the setting of
`core.logAllRefUpdates`.
+--format=<format>::
+ A string that interpolates `%(fieldname)` from a tag ref being shown
+ and the object it points at. The format is the same as
+ that of linkgit:git-for-each-ref[1]. When unspecified,
+ defaults to `%(refname:strip=2)`.
+
<tagname>::
The name of the tag to create, delete, or describe.
The new tag name must pass all checks defined by
@@ -198,12 +204,6 @@
The object that the new tag will refer to, usually a commit.
Defaults to HEAD.
-<format>::
- A string that interpolates `%(fieldname)` from a tag ref being shown
- and the object it points at. The format is the same as
- that of linkgit:git-for-each-ref[1]. When unspecified,
- defaults to `%(refname:strip=2)`.
-
CONFIGURATION
-------------
By default, 'git tag' in sign-with-default mode (-s) will use your
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt
index fda8516..9671423 100644
--- a/Documentation/git-update-ref.txt
+++ b/Documentation/git-update-ref.txt
@@ -129,8 +129,8 @@
symbolic refs before creating the log name) describing the change
in ref value. Log lines are formatted as:
- . oldsha1 SP newsha1 SP committer LF
-+
+ oldsha1 SP newsha1 SP committer LF
+
Where "oldsha1" is the 40 character hexadecimal value previously
stored in <ref>, "newsha1" is the 40 character hexadecimal value of
<newvalue> and "committer" is the committer's name, email address
@@ -138,8 +138,8 @@
Optionally with -m:
- . oldsha1 SP newsha1 SP committer TAB message LF
-+
+ oldsha1 SP newsha1 SP committer TAB message LF
+
Where all fields are as described above and "message" is the
value supplied to the -m option.
diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt
index 822ad59..998f52d 100644
--- a/Documentation/git-upload-pack.txt
+++ b/Documentation/git-upload-pack.txt
@@ -11,6 +11,7 @@
[verse]
'git-upload-pack' [--[no-]strict] [--timeout=<n>] [--stateless-rpc]
[--advertise-refs] <directory>
+
DESCRIPTION
-----------
Invoked by 'git fetch-pack', learns what
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 29a5b7e..d707e61 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -262,8 +262,8 @@
The porcelain format has a line per attribute. Attributes are listed with a
label and value separated by a single space. Boolean attributes (like 'bare'
and 'detached') are listed as a label only, and are only present if and only
-if the value is true. An empty line indicates the end of a worktree. For
-example:
+if the value is true. The first attribute of a worktree is always `worktree`,
+an empty line indicates the end of the record. For example:
------------
$ git worktree list --porcelain
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 8e6a92e..254f063 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -402,11 +402,11 @@
of Git object directories which can be used to search for Git
objects. New objects will not be written to these directories.
+
- Entries that begin with `"` (double-quote) will be interpreted
- as C-style quoted paths, removing leading and trailing
- double-quotes and respecting backslash escapes. E.g., the value
- `"path-with-\"-and-:-in-it":vanilla-path` has two paths:
- `path-with-"-and-:-in-it` and `vanilla-path`.
+Entries that begin with `"` (double-quote) will be interpreted
+as C-style quoted paths, removing leading and trailing
+double-quotes and respecting backslash escapes. E.g., the value
+`"path-with-\"-and-:-in-it":vanilla-path` has two paths:
+`path-with-"-and-:-in-it` and `vanilla-path`.
`GIT_DIR`::
If the `GIT_DIR` environment variable is set then it
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 92010b0..b8392fc 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -303,21 +303,21 @@
attribute. If you decide to use the `working-tree-encoding` attribute
in your repository, then it is strongly recommended to ensure that all
clients working with the repository support it.
-
- For example, Microsoft Visual Studio resources files (`*.rc`) or
- PowerShell script files (`*.ps1`) are sometimes encoded in UTF-16.
- If you declare `*.ps1` as files as UTF-16 and you add `foo.ps1` with
- a `working-tree-encoding` enabled Git client, then `foo.ps1` will be
- stored as UTF-8 internally. A client without `working-tree-encoding`
- support will checkout `foo.ps1` as UTF-8 encoded file. This will
- typically cause trouble for the users of this file.
-
- If a Git client, that does not support the `working-tree-encoding`
- attribute, adds a new file `bar.ps1`, then `bar.ps1` will be
- stored "as-is" internally (in this example probably as UTF-16).
- A client with `working-tree-encoding` support will interpret the
- internal contents as UTF-8 and try to convert it to UTF-16 on checkout.
- That operation will fail and cause an error.
++
+For example, Microsoft Visual Studio resources files (`*.rc`) or
+PowerShell script files (`*.ps1`) are sometimes encoded in UTF-16.
+If you declare `*.ps1` as files as UTF-16 and you add `foo.ps1` with
+a `working-tree-encoding` enabled Git client, then `foo.ps1` will be
+stored as UTF-8 internally. A client without `working-tree-encoding`
+support will checkout `foo.ps1` as UTF-8 encoded file. This will
+typically cause trouble for the users of this file.
++
+If a Git client, that does not support the `working-tree-encoding`
+attribute, adds a new file `bar.ps1`, then `bar.ps1` will be
+stored "as-is" internally (in this example probably as UTF-16).
+A client with `working-tree-encoding` support will interpret the
+internal contents as UTF-8 and try to convert it to UTF-16 on checkout.
+That operation will fail and cause an error.
- Reencoding content to non-UTF encodings can cause errors as the
conversion might not be UTF-8 round trip safe. If you suspect your
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index 4d63def..312b6f9 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -67,7 +67,8 @@
submodule.<name>.ignore::
Defines under what circumstances "git status" and the diff family show
a submodule as modified. The following values are supported:
-
++
+--
all;; The submodule will never be considered modified (but will
nonetheless show up in the output of status and commit when it has
been staged).
@@ -84,12 +85,14 @@
differences, and modifications to tracked and untracked files are
shown. This is the default option.
- If this option is also present in the submodules entry in .git/config
- of the superproject, the setting there will override the one found in
- .gitmodules.
- Both settings can be overridden on the command line by using the
- "--ignore-submodule" option. The 'git submodule' commands are not
- affected by this setting.
+If this option is also present in the submodules entry in .git/config
+of the superproject, the setting there will override the one found in
+.gitmodules.
+
+Both settings can be overridden on the command line by using the
+"--ignore-submodule" option. The 'git submodule' commands are not
+affected by this setting.
+--
submodule.<name>.shallow::
When set to true, a clone of this submodule will be performed as a
diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt
index 504c5f1..57999e9 100644
--- a/Documentation/gitsubmodules.txt
+++ b/Documentation/gitsubmodules.txt
@@ -169,11 +169,15 @@
A submodule is considered active,
- (a) if `submodule.<name>.active` is set to `true`
- or
- (b) if the submodule's path matches the pathspec in `submodule.active`
- or
- (c) if `submodule.<name>.url` is set.
+ a. if `submodule.<name>.active` is set to `true`
++
+or
+
+ b. if the submodule's path matches the pathspec in `submodule.active`
++
+or
+
+ c. if `submodule.<name>.url` is set.
and these are evaluated in this order.
diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
index 9c8982e..c0a326e 100644
--- a/Documentation/gitweb.conf.txt
+++ b/Documentation/gitweb.conf.txt
@@ -19,10 +19,12 @@
An example:
- # gitweb configuration file for http://git.example.org
- #
- our $projectroot = "/srv/git"; # FHS recommendation
- our $site_name = 'Example.org >> Repos';
+------------------------------------------------
+# gitweb configuration file for http://git.example.org
+#
+our $projectroot = "/srv/git"; # FHS recommendation
+our $site_name = 'Example.org >> Repos';
+------------------------------------------------
The configuration file is used to override the default settings that
@@ -357,6 +359,7 @@
+
For example, the following setting produces a breadcrumb trail like
"home / dev / projects / ..." where "projects" is the home link.
++
----------------------------------------------------------------------------
our @extra_breadcrumbs = (
[ 'home' => 'https://www.example.org/' ],
@@ -901,14 +904,16 @@
"zip" snapshots), while allowing individual projects to turn them off, put
the following in your GITWEB_CONFIG file:
- $feature{'blame'}{'default'} = [1];
- $feature{'blame'}{'override'} = 1;
+--------------------------------------------------------------------------------
+$feature{'blame'}{'default'} = [1];
+$feature{'blame'}{'override'} = 1;
- $feature{'pickaxe'}{'default'} = [1];
- $feature{'pickaxe'}{'override'} = 1;
+$feature{'pickaxe'}{'default'} = [1];
+$feature{'pickaxe'}{'override'} = 1;
- $feature{'snapshot'}{'default'} = ['zip', 'tgz'];
- $feature{'snapshot'}{'override'} = 1;
+$feature{'snapshot'}{'default'} = ['zip', 'tgz'];
+$feature{'snapshot'}{'override'} = 1;
+--------------------------------------------------------------------------------
If you allow overriding for the snapshot feature, you can specify which
snapshot formats are globally disabled. You can also add any command-line
