various fixes for docs
cover various fixes for docs
A small batch of fixes for the docs. All but the very first fixes formatting and similar stuff. The first one makes parsing 'git worktree list' more future-proof.
Andreas Heiduk (6):
doc: clarify boundaries of 'git worktree list --porcelain'
doc: fix ASCII art tab spacing
doc: fix inappropriate monospace formatting
doc: fix descripion for 'git tag --format'
doc: fix indentation of listing blocks in gitweb.conf.txt
doc: fix formatting in git-update-ref
Documentation/git-bisect-lk2009.txt | 30 ++++++++++++++--------------- Documentation/git-checkout.txt | 14 +++++++------- Documentation/git-merge-base.txt | 6 +++--- Documentation/git-tag.txt | 12 ++++++------ Documentation/git-update-ref.txt | 8 ++++---- Documentation/git-upload-pack.txt | 1 + Documentation/git-worktree.txt | 4 ++-- Documentation/git.txt | 10 +++++----- Documentation/gitattributes.txt | 30 ++++++++++++++--------------- Documentation/gitmodules.txt | 17 +++++++++------- Documentation/gitsubmodules.txt | 14 +++++++++----- Documentation/gitweb.conf.txt | 25 ++++++++++++++---------- 12 files changed, 92 insertions(+), 79 deletions(-)
Signature · 1 line
2.19.1
PATCH 1/6 doc: clarify boundaries of 'git worktree list --porcelain'
Defined delimiters for 'git worktree list --porcelain' make the format easier to parse in scripts. For example
sed -n '/^worktree ID$/,/^$/p'
extracts only the information for the worktree 'ID'.
The format did not changed since [1], only the guaranty is added.
[1] bb9c03b82a (worktree: add 'list' command, 2015-10-08)
Signed-off-by Andreas Heiduk <[email protected]>
--- Documentation/git-worktree.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-worktree.txt +2 -2
@@ -270,8 +270,8 @@ Porcelain Format 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
Signature · 1 line
2.19.1
Re: [PATCH 1/6] doc: clarify boundaries of 'git worktree list --porcelain'
Documentation/git-worktree.txt Porcelain Format · line 274
Quoted 9 lines · Andreas Heiduk
Documentation/git-worktree.txt +2
-2@@ -270,8 +270,8 @@ Porcelain Format 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:
When I suggested the --porcelain option for "git worktree list" and provided an example of its proposed output, the idea all along was that the "worktree" line itself would indicate start-of-stanza. A blank line between records is superfluous and unnecessary. Unfortunately, by the time the implementation was posted with blank line as stanza separator, I was not around to contest it, and it ended up in a release, after which point it was too late to change it.
So, the tl;dr is that this documentation update agrees with the original intention as I envisioned it (although I wouldn't be sad to see the mention of "blank line" dropped altogether, but that's perhaps a separate battle).
PATCH 2/6 doc: fix ASCII art tab spacing
In reply to Andreas HeidukFollowup to 5dd05ebf ("doc: fix merge-base ASCII art tab spacing", 2016-10-21)
Signed-off-by Andreas Heiduk <[email protected]>
--- Documentation/git-bisect-lk2009.txt | 30 ++++++++++++++--------------- Documentation/git-checkout.txt | 14 +++++++------- Documentation/git-merge-base.txt | 6 +++--- 3 files changed, 25 insertions(+), 25 deletions(-)
Documentation/git-bisect-lk2009.txt +15 -15
@@ -633,11 +633,11 @@ and so at step 3) we compute f(X). 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 @@ g(X) = min(number_of_ancestors(X), number_of_descendants(X)) 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 @@ forked of the main branch at a commit named "D" like this: ------------- 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"
Documentation/git-checkout.txt +7 -7
@@ -311,9 +311,9 @@ branch refers to a specific commit. Let's look at a repo with three 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 @@ to commit 'd': ------------ $ 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 @@ at what happens when we then checkout master: ------------ $ 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')
Documentation/git-merge-base.txt +3 -3
@@ -154,13 +154,13 @@ 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---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
Signature · 1 line
2.19.1
PATCH 3/6 doc: fix inappropriate monospace formatting
In reply to Andreas HeidukSigned-off-by Andreas Heiduk <[email protected]>
--- Documentation/git-upload-pack.txt | 1 + Documentation/git.txt | 10 +++++----- Documentation/gitattributes.txt | 30 +++++++++++++++--------------- Documentation/gitmodules.txt | 17 ++++++++++------- Documentation/gitsubmodules.txt | 14 +++++++++----- 5 files changed, 40 insertions(+), 32 deletions(-)
Documentation/git-upload-pack.txt +1 -0
@@ -11,6 +11,7 @@ SYNOPSIS [verse] 'git-upload-pack' [--[no-]strict] [--timeout=<n>] [--stateless-rpc] [--advertise-refs] <directory> + DESCRIPTION ----------- Invoked by 'git fetch-pack', learns what
Documentation/git.txt +5 -5
@@ -402,11 +402,11 @@ Git so take care if using a foreign front-end. 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
Documentation/gitattributes.txt +15 -15
@@ -303,21 +303,21 @@ number of pitfalls: 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
Documentation/gitmodules.txt +10 -7
@@ -67,7 +67,8 @@ submodule.<name>.fetchRecurseSubmodules:: 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 @@ submodule.<name>.ignore:: 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
Documentation/gitsubmodules.txt +9 -5
@@ -169,11 +169,15 @@ ACTIVE SUBMODULES 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.
Signature · 1 line
2.19.1
PATCH 4/6 doc: fix descripion for 'git tag --format'
In reply to Andreas HeidukThe '--format=<format>' is now listed in the 'OPTIONS' section, not only the '<format>' string itself. The description moved up a few paragraphs because '<format>' is not a standalone paramater but a parameter for the option '--format'.
Signed-off-by Andreas Heiduk <[email protected]>
--- Documentation/git-tag.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)
Documentation/git-tag.txt +6 -6
@@ -187,6 +187,12 @@ This option is only applicable when listing tags without annotation lines. `--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 @@ This option is only applicable when listing tags without annotation lines. 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
Signature · 1 line
2.19.1
PATCH 5/6 doc: fix indentation of listing blocks in gitweb.conf.txt
In reply to Andreas Heiduk'gitweb.conf.txt' uses inconsistent indentation in listing blocks and a mix of listing blocks and literal paragraphs. Both didn't look pretty in the rendered HTML page.
Signed-off-by Andreas Heiduk <[email protected]>
--- Documentation/gitweb.conf.txt | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-)
Documentation/gitweb.conf.txt +15 -10
@@ -19,10 +19,12 @@ end of a line is ignored. See *perlsyn*(1) for details. 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 @@ $home_link_str:: + 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 @@ To enable blame, pickaxe search, and snapshot support (allowing "tar.gz" and "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
Signature · 1 line
2.19.1
PATCH 6/6 doc: fix formatting in git-update-ref
In reply to Andreas HeidukRemove the parapgraph numbers from lines explaining the reflog format and typeset these lines in monospace.
Signed-off-by Andreas Heiduk <[email protected]>
--- Documentation/git-update-ref.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/git-update-ref.txt +4 -4
@@ -129,8 +129,8 @@ a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all 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 @@ and date in the standard Git committer ident format. 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.
Signature · 1 line
2.19.1