Skip to contentSkip to conversation

some documentation changes from the beginning of the alphabet

PATCH In review Frederick Eaton 4 participants 15 messages Sep 19, 2018 – Sep 21, 2018 Documentation

lore
Share & tools
lore
#0 lore raw

cover some documentation changes from the beginning of the alphabet

I've never sent patches using git before so I thought it would be useful to make a small test.

I read ./Documentation/SubmittingPatches and I sent these to myself and practiced applying them using git am, and I also compiled and checked the revised manual pages to see that they format correctly. Unfortunately it was too late to run 'git diff --check' because I had already committed the changes to my repo, but I don't see any whitespace highlighted when I run 'git log -p'.

I'm sure I'm doing something wrong, so please let me know what it is!

Here's the command I'll use to send the messages (without --dry-run):

git send-email --to "Junio C Hamano <[email protected]>" --cc [email protected] --cc-cmd ./contrib/contacts/git-contacts outgoing/ --dry-run

By the way for some reason git-contacts shows more names when I run it on the patch hash than when I give it the patch name:

$ ./contrib/contacts/git-contacts 222580cb60ee64f7b81fed64ec8fbfc81952557f
Sébastien Guimmara <[email protected]>
Nguyễn Thái Ngọc Duy <[email protected]>
Eric Sunshine <[email protected]>
Junio C Hamano <[email protected]>
$ ./contrib/contacts/git-contacts ./outgoing/0002-git-column.1-clarify-initial-description-provide-exa.patch                                
Junio C Hamano <[email protected]>

Not sure what's going on here, but the changes I propose seem fairly straightforward...(?)

Frederick Eaton (3):
git-archimport.1: specify what kind of Arch we're talking about git-column.1: clarify initial description, provide examples git-describe.1: clarify that "human readable" is also git-readable

 Documentation/git-archimport.txt |  5 +++--
 Documentation/git-column.txt     | 35 ++++++++++++++++++++++++++++++--
 Documentation/git-describe.txt   |  4 +++-
 3 files changed, 39 insertions(+), 5 deletions(-)
Signature · 1 line
2.19.0
#1 lore raw

PATCH 1/3 git-archimport.1: specify what kind of Arch we're talking about

Is it a CPU architecture? Is it Arch Linux? If you search for "arch repository", nothing relevant comes up. Let's call it GNU Arch so people can find it with search engines.

---
 Documentation/git-archimport.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/git-archimport.txt +3 -2
index ea7065336..a595a0ffe 100644
@@ -3,7 +3,7 @@ git-archimport(1)
 
 NAME
 ----
-git-archimport - Import an Arch repository into Git
+git-archimport - Import a GNU Arch repository into Git
 
 
 SYNOPSIS
@@ -14,7 +14,8 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Imports a project from one or more Arch repositories. It will follow branches
+Imports a project from one or more GNU Arch repositories.
+It will follow branches
 and repositories within the namespaces defined by the <archive/branch>
 parameters supplied. If it cannot find the remote branch a merge comes from
 it will just import it as a regular commit. If it can find it, it will mark it
Signature · 1 line
2.19.0
#2 lore raw

Re: [PATCH 1/3] git-archimport.1: specify what kind of Arch we're talking about

Quoted 8 lines · Frederick Eaton

Is it a CPU architecture? Is it Arch Linux? If you search for "arch repository", nothing relevant comes up. Let's call it GNU Arch so people can find it with search engines.

---
 Documentation/git-archimport.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

I think "Is it a CPU archtecture?" is a red-herring, but between "What is an Arch Repository?" and "What is GNU Arch?" there indeed is a vast difference in the quality of information readers would get; with the proposed commit log message that ends with "so people can find it with search engines", I am reasonably sure this is an improvement worth having.

Thanks.

Quoted 24 lines
Documentation/git-archimport.txt +3 -2
index ea7065336..a595a0ffe 100644
@@ -3,7 +3,7 @@ git-archimport(1)
 
 NAME
 ----
-git-archimport - Import an Arch repository into Git
+git-archimport - Import a GNU Arch repository into Git
 
 
 SYNOPSIS
@@ -14,7 +14,8 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Imports a project from one or more Arch repositories. It will follow branches
+Imports a project from one or more GNU Arch repositories.
+It will follow branches
 and repositories within the namespaces defined by the <archive/branch>
 parameters supplied. If it cannot find the remote branch a merge comes from
 it will just import it as a regular commit. If it can find it, it will mark it
#3 lore raw

Re: [PATCH 1/3] git-archimport.1: specify what kind of Arch we're talking about

Quoted 1 line

I think "Is it a CPU archtecture?" is a red-herring, but between

It wasn't meant to be a red-herring though. Plenty of Linux distributions have different architecture-specific package repos, and arch is a common abbreviation for architecture. This only comes up if you search for the full word e.g. "linux architecture repository" since other wise Arch Linux dominates all the search results.

A bit of a tangent...

Frederick

Quoted 7 lines

"What is an Arch Repository?" and "What is GNU Arch?" there indeed is a vast difference in the quality of information readers would get; with the proposed commit log message that ends with "so people can find it with search engines", I am reasonably sure this is an improvement worth having.

Thanks.

#4 lore raw

PATCH 2/3 git-column.1: clarify initial description, provide examples

In reply to Frederick Eaton

When I read this man page I couldn't figure out what kind of input it was referring to, or how input was being put into columns, or where I should look for the syntax of the --mode option.

---
 Documentation/git-column.txt | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)
Documentation/git-column.txt +33 -2
index 03d18465d..5bbb51068 100644
@@ -13,7 +13,10 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-This command formats its input into multiple columns.
+This command formats the lines of its standard input into a table with
+multiple columns. Each input line occupies one cell of the table. It
+is used internally by other git commands to format output into
+columns.
 
 OPTIONS
 -------
@@ -23,7 +26,7 @@ OPTIONS
 
 --mode=<mode>::
 	Specify layout mode. See configuration variable column.ui for option
-	syntax.
+	syntax (in git-config(1)).
 
 --raw-mode=<n>::
 	Same as --mode but take mode encoded as a number. This is mainly used
@@ -43,6 +46,34 @@ OPTIONS
 --padding=<N>::
 	The number of spaces between columns. One space by default.
 
+EXAMPLES
+------
+
+Format data by columns:
+------------
+$ seq 1 24 | git column --mode=column --padding=5
+1      4      7      10     13     16     19     22
+2      5      8      11     14     17     20     23
+3      6      9      12     15     18     21     24
+------------
+
+Format data by rows:
+------------
+$ seq 1 21 | git column --mode=row --padding=5
+1      2      3      4      5      6      7
+8      9      10     11     12     13     14
+15     16     17     18     19     20     21
+------------
+
+List some tags in a table with unequal column widths:
+------------
+$ git tag --list 'v2.4.*' --column=row,dense
+v2.4.0  v2.4.0-rc0  v2.4.0-rc1  v2.4.0-rc2  v2.4.0-rc3
+v2.4.1  v2.4.10     v2.4.11     v2.4.12     v2.4.2
+v2.4.3  v2.4.4      v2.4.5      v2.4.6      v2.4.7
+v2.4.8  v2.4.9
+------------
+
 GIT
 ---
 Part of the linkgit:git[1] suite
Signature · 1 line
2.19.0
#5 lore raw

Re: [PATCH 2/3] git-column.1: clarify initial description, provide examples

Quoted 8 lines · Frederick Eaton

When I read this man page I couldn't figure out what kind of input it was referring to, or how input was being put into columns, or where I should look for the syntax of the --mode option.

---
 Documentation/git-column.txt | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

I'll defer this to its primary author.

Quoted 61 lines
Documentation/git-column.txt +33 -2
index 03d18465d..5bbb51068 100644
@@ -13,7 +13,10 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-This command formats its input into multiple columns.
+This command formats the lines of its standard input into a table with
+multiple columns. Each input line occupies one cell of the table. It
+is used internally by other git commands to format output into
+columns.
 
 OPTIONS
 -------
@@ -23,7 +26,7 @@ OPTIONS
 
 --mode=<mode>::
 	Specify layout mode. See configuration variable column.ui for option
-	syntax.
+	syntax (in git-config(1)).
 
 --raw-mode=<n>::
 	Same as --mode but take mode encoded as a number. This is mainly used
@@ -43,6 +46,34 @@ OPTIONS
 --padding=<N>::
 	The number of spaces between columns. One space by default.
 
+EXAMPLES
+------
+
+Format data by columns:
+------------
+$ seq 1 24 | git column --mode=column --padding=5
+1      4      7      10     13     16     19     22
+2      5      8      11     14     17     20     23
+3      6      9      12     15     18     21     24
+------------
+
+Format data by rows:
+------------
+$ seq 1 21 | git column --mode=row --padding=5
+1      2      3      4      5      6      7
+8      9      10     11     12     13     14
+15     16     17     18     19     20     21
+------------
+
+List some tags in a table with unequal column widths:
+------------
+$ git tag --list 'v2.4.*' --column=row,dense
+v2.4.0  v2.4.0-rc0  v2.4.0-rc1  v2.4.0-rc2  v2.4.0-rc3
+v2.4.1  v2.4.10     v2.4.11     v2.4.12     v2.4.2
+v2.4.3  v2.4.4      v2.4.5      v2.4.6      v2.4.7
+v2.4.8  v2.4.9
+------------
+
 GIT
 ---
 Part of the linkgit:git[1] suite
#6 lore raw

Re: [PATCH 2/3] git-column.1: clarify initial description, provide examples

Quoted 6 lines · Junio C Hamano

Documentation/git-column.txt OPTIONS · line 29

Quoted 6 lines
Documentation/git-column.txt +1 -1
@@ -23,7 +26,7 @@ OPTIONS
 
 --mode=<mode>::
 	Specify layout mode. See configuration variable column.ui for option
-	syntax.
+	syntax (in git-config(1)).

I think we usually link to other commands with "linkgit", like linkgit:git-config[1]

Other than that, the rest looks good.
--
Duy

#7 lore raw

Re: [PATCH 2/3] git-column.1: clarify initial description, provide examples

Quoted 11 lines · Duy Nguyen
Quoted 6 lines · Junio C Hamano

Documentation/git-column.txt OPTIONS · line 29

Quoted 6 lines
Documentation/git-column.txt +1 -1
@@ -23,7 +26,7 @@ OPTIONS
 
 --mode=<mode>::
 	Specify layout mode. See configuration variable column.ui for option
-	syntax.
+	syntax (in git-config(1)).

I think we usually link to other commands with "linkgit", like linkgit:git-config[1]

Quoted 1 line

Other than that, the rest looks good.

Thank you, then do I edit the patch and resubmit as PATCH v2 with the message ID and all that?

Frederick

#8 lore raw

Re: [PATCH 2/3] git-column.1: clarify initial description, provide examples

Quoted 12 lines · On Thu, Sep 20, 2018 at 1:47 PM <[email protected]> wrote:
Quoted 10 lines · Duy Nguyen
Quoted 6 lines · Junio C Hamano

Documentation/git-column.txt OPTIONS · line 29

Quoted 6 lines
Documentation/git-column.txt +1 -1
@@ -23,7 +26,7 @@ OPTIONS
 
 --mode=<mode>::
  Specify layout mode. See configuration variable column.ui for option
- syntax.
+ syntax (in git-config(1)).

I think we usually link to other commands with "linkgit", like linkgit:git-config[1]

Quoted 2 lines

Thank you, then do I edit the patch and resubmit as PATCH v2 with the message ID and all that?

Editing the patch directly is not recommended. More typical would be to use "git rebase -i" and/or "git commit --amend" to make changes to the commits themselves (that is, rewrite history), taking review comments into account (and generally polishing the changes). Once the edits are complete, re-generate the patches with git-format-patch and re-send the entire series as v2 with git-send-email (or some people skip git-format-patch and go directly to git-send-email to both format and send the patches as one step).

You can use the -v option of git-format-patch to mark the series as v2.

When sending v2 via git-send-email, you can use the --in-reply-to option with the message ID of the v1 cover letter to tie the re-roll to the original. (The message ID of the v1 cover letter is "[email protected]".)

#9 lore raw

Re: [PATCH 2/3] git-column.1: clarify initial description, provide examples

In reply to [email protected]
Quoted 12 lines · [email protected] writes:
Quoted 11 lines · Duy Nguyen
Quoted 6 lines · Junio C Hamano

Review OPTIONS · line 29

Quoted 6 lines
(quoted diff) +1 -1
@@ -23,7 +26,7 @@ OPTIONS
 
 --mode=<mode>::
 	Specify layout mode. See configuration variable column.ui for option
-	syntax.
+	syntax (in git-config(1)).

I think we usually link to other commands with "linkgit", like linkgit:git-config[1]

Quoted 6 lines
Quoted 1 line

Other than that, the rest looks good.

Thank you, then do I edit the patch and resubmit as PATCH v2 with the message ID and all that?

Frederick

If this is the only change in the whole 3 patches, then I can just squash in the following to save one round-trip.

 Documentation/git-column.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-column.txt +1 -1
index 5bbb51068e..763afabb6d 100644
@@ -26,7 +26,7 @@ OPTIONS
 
 --mode=<mode>::
 	Specify layout mode. See configuration variable column.ui for option
-	syntax (in git-config(1)).
+	syntax in linkgit:git-config[1].
 
 --raw-mode=<n>::
 	Same as --mode but take mode encoded as a number. This is mainly used
#10 lore raw

Re: [PATCH 2/3] git-column.1: clarify initial description, provide examples

Thank you Junio, maybe I will have another chance to get practice sending a v2 patch.

Quoted 41 lines · Junio C Hamano
Quoted 12 lines · [email protected] writes:
Quoted 11 lines · Duy Nguyen
Quoted 6 lines · Junio C Hamano

Documentation/git-column.txt OPTIONS · line 29

Quoted 6 lines
Documentation/git-column.txt +1 -1
@@ -23,7 +26,7 @@ OPTIONS
 
 --mode=<mode>::
 	Specify layout mode. See configuration variable column.ui for option
-	syntax.
+	syntax (in git-config(1)).

I think we usually link to other commands with "linkgit", like linkgit:git-config[1]

Quoted 6 lines
Quoted 1 line

Other than that, the rest looks good.

Thank you, then do I edit the patch and resubmit as PATCH v2 with the message ID and all that?

Frederick

If this is the only change in the whole 3 patches, then I can just squash in the following to save one round-trip.

 Documentation/git-column.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-column.txt +1 -1
index 5bbb51068e..763afabb6d 100644
@@ -26,7 +26,7 @@ OPTIONS
 
 --mode=<mode>::
 	Specify layout mode. See configuration variable column.ui for option
-	syntax (in git-config(1)).
+	syntax in linkgit:git-config[1].
 
 --raw-mode=<n>::
 	Same as --mode but take mode encoded as a number. This is mainly used
#11 lore raw

PATCH 3/3 git-describe.1: clarify that "human readable" is also git-readable

In reply to Frederick Eaton

The caption uses the term "human readable", but the DESCRIPTION did not explain this in context.

---
 Documentation/git-describe.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/git-describe.txt +3 -1
index e027fb8c4..ccdc5f83d 100644
@@ -18,7 +18,9 @@ The command finds the most recent tag that is reachable from a
 commit.  If the tag points to the commit, then only the tag is
 shown.  Otherwise, it suffixes the tag name with the number of
 additional commits on top of the tagged object and the
-abbreviated object name of the most recent commit.
+abbreviated object name of the most recent commit. The result
+is a "human-readable" object name which can also be used to
+identify the commit to other git commands.
 
 By default (without --all or --tags) `git describe` only shows
 annotated tags.  For more information about creating annotated tags
Signature · 1 line
2.19.0
#12 lore raw
In reply to Frederick Eaton
Quoted 2 lines · Frederick Eaton

I've never sent patches using git before so I thought it would be useful to make a small test.

... eh, welcome ;-)

Quoted 6 lines

I read ./Documentation/SubmittingPatches and I sent these to myself and practiced applying them using git am, and I also compiled and checked the revised manual pages to see that they format correctly. Unfortunately it was too late to run 'git diff --check' because I had already committed the changes to my repo, but I don't see any whitespace highlighted when I run 'git log -p'.

Thanks for being diligent.

Quoted 10 lines

By the way for some reason git-contacts shows more names when I run it on the patch hash than when I give it the patch name:

$ ./contrib/contacts/git-contacts 222580cb60ee64f7b81fed64ec8fbfc81952557f
Sébastien Guimmara <[email protected]>
Nguyễn Thái Ngọc Duy <[email protected]>
Eric Sunshine <[email protected]>
Junio C Hamano <[email protected]>
$ ./contrib/contacts/git-contacts ./outgoing/0002-git-column.1-clarify-initial-description-provide-exa.patch                                
Junio C Hamano <[email protected]>

I've never trusted what git-contacts say, but the latter one certainly looks strange, as

	git log --no-merges Documentation/git-column.txt

makes it clear that I have nothing to do with it ;-). Perhaps the tool gives too much credit for Signed-off-by: footer, or something.

#13 lore raw
Quoted 12 lines · Junio C Hamano
Quoted 10 lines · Frederick Eaton

By the way for some reason git-contacts shows more names when I run it on the patch hash than when I give it the patch name:

$ ./contrib/contacts/git-contacts 222580cb60ee64f7b81fed64ec8fbfc81952557f
Sébastien Guimmara <[email protected]>
Nguyễn Thái Ngọc Duy <[email protected]>
Eric Sunshine <[email protected]>
Junio C Hamano <[email protected]>
$ ./contrib/contacts/git-contacts ./outgoing/0002-git-column.1-clarify-initial-description-provide-exa.patch
Junio C Hamano <[email protected]>
Quoted 2 lines

I've never trusted what git-contacts say, but the latter one certainly looks strange [...]

I don't use git-contacts, but the first invocation isn't consulting just a single commit but rather a range of commits. From git-contacts documentation:

Input consists of one or more patch files or revision arguments. A revision argument can be a range or a single <rev> which is interpreted as <rev>..HEAD, thus the same revision arguments are accepted as for linkgit:git-format-patch[1]. Patch files and revision arguments can be combined in the same invocation.

So, you are actually running git-contacts on the range 222580cb..HEAD, and 222580cb isn't even one of the patches being consulted (due to how the range syntax does not include the argument to the left of ".."). To consult just that one commit, you'd want perhaps:

    git-contacts 222580cb^..222580cb
Quoted 6 lines

[...] as,

        git log --no-merges Documentation/git-column.txt

makes it clear that I have nothing to do with it ;-). Perhaps the tool gives too much credit for Signed-off-by: footer, or something.

Since git-contacts can be used as git-send-email's --cc-cmd, it can potentially be invoked many times, and it's a slow command (due to all the "blaming" via git-blame). As an optimization, git-contacts limits the timeframe of the blame via git-blame's --since option, with a hardcoded limit of 5 years. So, the git-blame invocation made by git-contacts for this patch file is:

    git blame --porcelain -C -L13,+7 -L23,+7 -L43,+6 \
        --since 5-years-ago \
        4a189fff51b1^ -- Documentation/git-column.txt

Since the lines changed by the patch have not been touched within that timeframe, git-blame assigns those lines to boundary commit 128a96c984 (Update draft release notes to 1.8.5 for the fifth batch of topics, 2013-09-20), which was authored by Junio, which is why he shows up as the only "contact".

If we remove the --since restriction:

    git blame --porcelain -C -L13,+7 -L23,+7 -L43,+6 \
        4a189fff51b1^ -- Documentation/git-column.txt

then the lines are correctly "blamed" to Duy via commit 7e29b8254f (Add column layout skeleton and git-column, 2012-04-21).

The "Limitations" section of the git-contacts documentation says this:

Several conditions controlling a person's significance are currently hard-coded, such as minimum participation level (10%), blame date-limiting (5 years), and -C level for detecting moved and copied lines (a single -C). In the future, these conditions may become configurable.

So, this sort of potential issue was understood. Felipe's git-related[1], from which git-contacts arose, eventually grew the ability to tweak these hard-coded values via command-line options. The same could be done for git-contacts. Patches are welcome.

[1]: https://github.com/felipec/git-related

#14 lore raw
Quoted 1 line

Patches are welcome.

I'd be happy to patch git-contacts to link to the message you just sent, then maybe someone more qualified would know where to start... :)

Frederick

Quoted 80 lines · Eric Sunshine
Quoted 12 lines · Junio C Hamano
Quoted 10 lines · Frederick Eaton

By the way for some reason git-contacts shows more names when I run it on the patch hash than when I give it the patch name:

$ ./contrib/contacts/git-contacts 222580cb60ee64f7b81fed64ec8fbfc81952557f
Sébastien Guimmara <[email protected]>
Nguyễn Thái Ngọc Duy <[email protected]>
Eric Sunshine <[email protected]>
Junio C Hamano <[email protected]>
$ ./contrib/contacts/git-contacts ./outgoing/0002-git-column.1-clarify-initial-description-provide-exa.patch
Junio C Hamano <[email protected]>
Quoted 2 lines

I've never trusted what git-contacts say, but the latter one certainly looks strange [...]

I don't use git-contacts, but the first invocation isn't consulting just a single commit but rather a range of commits. From git-contacts documentation:

Input consists of one or more patch files or revision arguments. A revision argument can be a range or a single <rev> which is interpreted as <rev>..HEAD, thus the same revision arguments are accepted as for linkgit:git-format-patch[1]. Patch files and revision arguments can be combined in the same invocation.

So, you are actually running git-contacts on the range 222580cb..HEAD, and 222580cb isn't even one of the patches being consulted (due to how the range syntax does not include the argument to the left of ".."). To consult just that one commit, you'd want perhaps:

    git-contacts 222580cb^..222580cb
Quoted 6 lines

[...] as,

        git log --no-merges Documentation/git-column.txt

makes it clear that I have nothing to do with it ;-). Perhaps the tool gives too much credit for Signed-off-by: footer, or something.

Since git-contacts can be used as git-send-email's --cc-cmd, it can potentially be invoked many times, and it's a slow command (due to all the "blaming" via git-blame). As an optimization, git-contacts limits the timeframe of the blame via git-blame's --since option, with a hardcoded limit of 5 years. So, the git-blame invocation made by git-contacts for this patch file is:

    git blame --porcelain -C -L13,+7 -L23,+7 -L43,+6 \
        --since 5-years-ago \
        4a189fff51b1^ -- Documentation/git-column.txt

Since the lines changed by the patch have not been touched within that timeframe, git-blame assigns those lines to boundary commit 128a96c984 (Update draft release notes to 1.8.5 for the fifth batch of topics, 2013-09-20), which was authored by Junio, which is why he shows up as the only "contact".

If we remove the --since restriction:

    git blame --porcelain -C -L13,+7 -L23,+7 -L43,+6 \
        4a189fff51b1^ -- Documentation/git-column.txt

then the lines are correctly "blamed" to Duy via commit 7e29b8254f (Add column layout skeleton and git-column, 2012-04-21).

The "Limitations" section of the git-contacts documentation says this:

Several conditions controlling a person's significance are currently hard-coded, such as minimum participation level (10%), blame date-limiting (5 years), and -C level for detecting moved and copied lines (a single -C). In the future, these conditions may become configurable.

So, this sort of potential issue was understood. Felipe's git-related[1], from which git-contacts arose, eventually grew the ability to tweak these hard-coded values via command-line options. The same could be done for git-contacts. Patches are welcome.

[1]: https://github.com/felipec/git-related