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'
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:
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
-------------
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"
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')
^
|
------------
$ 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')
^
|
------------
$ 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')
`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
`--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
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
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
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.
[verse]
'git-upload-pack' [--[no-]strict] [--timeout=<n>] [--stateless-rpc]
[--advertise-refs] <directory>
+
DESCRIPTION
-----------
Invoked by 'git fetch-pack', learns what
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
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
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
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).
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
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.
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
+
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/' ],
"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