* [PATCH 1/2] Rewrite man page explanation of git log's "--log-size" option @ 2013-11-13 6:21 Jason St. John 2013-11-13 6:21 ` [PATCH 2/2] Fix minor grammatical and other formatting issues in the "git log" man page Jason St. John 0 siblings, 1 reply; 5+ messages in thread From: Jason St. John @ 2013-11-13 6:21 UTC (permalink / raw) To: git; +Cc: Jason St. John Documentation/git-log.txt: --log-size was added in commit 9fa3465, and the commit message contained a satisfactory explanation; however, the man page entry for it was unclear and cryptic. Thanks-to: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Jason St. John <jstjohn@purdue.edu> --- This is effectively a resubmit of my previous patch here: http://marc.info/?l=git&m=138395803808196&w=2 Thanks to Jonathan Nieder for writing the text used in this commit: http://marc.info/?l=git&m=138395887208373&w=2 Documentation/git-log.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 34097ef..a5de513 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -56,11 +56,11 @@ Note that this affects all diff-based output types, e.g. those produced by --stat etc. --log-size:: - Before the log message print out its size in bytes. Intended - mainly for porcelain tools consumption. If Git is unable to - produce a valid value size is set to zero. - Note that only message is considered, if also a diff is shown - its size is not included. + + Include a line ``log size <number>'' in the output for each commit, + where <number> is the length of that commit's message in bytes. + Intended to speed up tools that read log messages from `git log` + output by allowing them to allocate space in advance. -L <start>,<end>:<file>:: -L :<regex>:<file>:: -- 1.8.4.2 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH 2/2] Fix minor grammatical and other formatting issues in the "git log" man page 2013-11-13 6:21 [PATCH 1/2] Rewrite man page explanation of git log's "--log-size" option Jason St. John @ 2013-11-13 6:21 ` Jason St. John 2013-11-13 21:56 ` Junio C Hamano 0 siblings, 1 reply; 5+ messages in thread From: Jason St. John @ 2013-11-13 6:21 UTC (permalink / raw) To: git; +Cc: Jason St. John Documentation/git-log.txt: -- replace single quotes around options/commands with backticks -- use single quotes around references to sections -- replaced some double quotes with proper AsciiDoc quotes (e.g. ``foo'') -- use backticks around files and file paths -- use title case when referring to section headings -- use backticks around option arguments/defaults Signed-off-by: Jason St. John <jstjohn@purdue.edu> --- When working on this commit, I noticed a difference in how options and option descriptions are separated (e.g. with a blank line or not). At least with Vim's syntax highlighting, if there is a blank line between the option and its description, the text block is all colored the same; however, if there isn't a blank line, then the text block is not specially colored. Is there an existing convention for how this should be done? Documentation/git-log.txt | 43 +++++++++++++++++++++---------------------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index a5de513..1f7bc67 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -15,9 +15,9 @@ DESCRIPTION ----------- Shows the commit logs. -The command takes options applicable to the 'git rev-list' +The command takes options applicable to the `git rev-list` command to control what is shown and how, and options applicable to -the 'git diff-*' commands to control how the changes +the `git diff-*` commands to control how the changes each commit introduces are shown. @@ -42,21 +42,20 @@ OPTIONS --use-mailmap:: Use mailmap file to map author and committer names and email - to canonical real names and email addresses. See + addresses to canonical real names and email addresses. See linkgit:git-shortlog[1]. --full-diff:: - Without this flag, "git log -p <path>..." shows commits that + Without this flag, `git log -p <path>...` shows commits that touch the specified paths, and diffs about the same specified paths. With this, the full diff is shown for commits that touch the specified paths; this means that "<path>..." limits only commits, and doesn't limit diff for those commits. + Note that this affects all diff-based output types, e.g. those -produced by --stat etc. +produced by `--stat`, etc. --log-size:: - Include a line ``log size <number>'' in the output for each commit, where <number> is the length of that commit's message in bytes. Intended to speed up tools that read log messages from `git log` @@ -64,7 +63,6 @@ produced by --stat etc. -L <start>,<end>:<file>:: -L :<regex>:<file>:: - Trace the evolution of the line range given by "<start>,<end>" (or the funcname regex <regex>) within the <file>. You may not give any pathspec limiters. This is currently limited to @@ -80,16 +78,16 @@ include::line-range-format.txt[] whole history leading to the current commit). `origin..HEAD` specifies all the commits reachable from the current commit (i.e. `HEAD`), but not from `origin`. For a complete list of - ways to spell <revision range>, see the "Specifying Ranges" + ways to spell <revision range>, see the 'Specifying Ranges' section of linkgit:gitrevisions[7]. [\--] <path>...:: Show only commits that are enough to explain how the files - that match the specified paths came to be. See "History - Simplification" below for details and other simplification + that match the specified paths came to be. See 'History + Simplification' below for details and other simplification modes. + -Paths may need to be prefixed with "\-- " to separate them from +Paths may need to be prefixed with ``\-- '' to separate them from options or the revision range, when confusion arises. include::rev-list-options.txt[] @@ -113,12 +111,12 @@ EXAMPLES `git log v2.6.12.. include/scsi drivers/scsi`:: Show all commits since version 'v2.6.12' that changed any file - in the include/scsi or drivers/scsi subdirectories + in the `include/scsi` or `drivers/scsi` subdirectories `git log --since="2 weeks ago" -- gitk`:: Show the changes during the last two weeks to the file 'gitk'. - The "--" is necessary to avoid confusion with the *branch* named + The ``--'' is necessary to avoid confusion with the *branch* named 'gitk' `git log --name-status release..test`:: @@ -129,7 +127,7 @@ EXAMPLES `git log --follow builtin/rev-list.c`:: - Shows the commits that changed builtin/rev-list.c, including + Shows the commits that changed `builtin/rev-list.c`, including those commits that occurred before the file was given its present name. @@ -147,17 +145,18 @@ EXAMPLES `git log -p -m --first-parent`:: Shows the history including change diffs, but only from the - "main branch" perspective, skipping commits that come from merged + ``main branch'' perspective, skipping commits that come from merged branches, and showing full diffs of changes introduced by the merges. This makes sense only when following a strict policy of merging all topic branches when staying on a single integration branch. `git log -L '/int main/',/^}/:main.c`:: - Shows how the function `main()` in the file 'main.c' evolved + Shows how the function `main()` in the file `main.c` evolved over time. `git log -3`:: + Limits the number of commits to show to 3. DISCUSSION @@ -172,12 +171,12 @@ See linkgit:git-config[1] for core variables and linkgit:git-diff[1] for settings related to diff generation. format.pretty:: - Default for the `--format` option. (See "PRETTY FORMATS" above.) - Defaults to "medium". + Default for the `--format` option. (See 'Pretty Formats' above.) + Defaults to `medium`. i18n.logOutputEncoding:: - Encoding to use when displaying logs. (See "Discussion", above.) - Defaults to the value of `i18n.commitEncoding` if set, UTF-8 + Encoding to use when displaying logs. (See 'Discussion' above.) + Defaults to the value of `i18n.commitEncoding` if set, and UTF-8 otherwise. log.date:: @@ -186,7 +185,7 @@ log.date:: dates like `Sat May 8 19:35:34 2010 -0500`. log.showroot:: - If `false`, 'git log' and related commands will not treat the + If `false`, `git log` and related commands will not treat the initial commit as a big creation event. Any root commits in `git log -p` output would be shown without a diff attached. The default is `true`. @@ -197,7 +196,7 @@ mailmap.*:: notes.displayRef:: Which refs, in addition to the default set by `core.notesRef` or 'GIT_NOTES_REF', to read notes from when showing commit - messages with the 'log' family of commands. See + messages with the `log` family of commands. See linkgit:git-notes[1]. + May be an unabbreviated ref name or a glob and may be specified -- 1.8.4.2 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH 2/2] Fix minor grammatical and other formatting issues in the "git log" man page 2013-11-13 6:21 ` [PATCH 2/2] Fix minor grammatical and other formatting issues in the "git log" man page Jason St. John @ 2013-11-13 21:56 ` Junio C Hamano 2013-11-15 1:44 ` Jason St. John 0 siblings, 1 reply; 5+ messages in thread From: Junio C Hamano @ 2013-11-13 21:56 UTC (permalink / raw) To: Jason St. John; +Cc: git "Jason St. John" <jstjohn@purdue.edu> writes: > Documentation/git-log.txt: > -- replace single quotes around options/commands with backticks > -- use single quotes around references to sections > -- replaced some double quotes with proper AsciiDoc quotes (e.g. > ``foo'') > -- use backticks around files and file paths > -- use title case when referring to section headings > -- use backticks around option arguments/defaults > > Signed-off-by: Jason St. John <jstjohn@purdue.edu> > --- > When working on this commit, I noticed a difference in how options and > option descriptions are separated (e.g. with a blank line or not). At least > with Vim's syntax highlighting, if there is a blank line between the option > and its description, the text block is all colored the same; however, if > there isn't a blank line, then the text block is not specially colored. > > Is there an existing convention for how this should be done? I do not think we have a written rule or convention (and I do not know if we want one). While reading the text in the source form (and the point of choosing AsciiDoc was to be able to read the docs without formatting), I personally have a slight preference to immediately follow the body text to the label in the labelled list, and a blank line after the item, i.e. item label:: This describes the item. next item label:: This describes the next item. as it makes it clear that the body belongs to the heading that precedes it. But it does help to have a blank between the label and the beginning of the body when reflowing the body with fill-paragraph, i.e. item label:: This describes the item. You say that it is also easier on Vim to have the blank line there, so perhaps we may want to aim for updating the documentation over time to consistently do so. I dunno. ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH 2/2] Fix minor grammatical and other formatting issues in the "git log" man page 2013-11-13 21:56 ` Junio C Hamano @ 2013-11-15 1:44 ` Jason St. John 2013-11-15 1:47 ` Jason St. John 0 siblings, 1 reply; 5+ messages in thread From: Jason St. John @ 2013-11-15 1:44 UTC (permalink / raw) To: git On Wed, Nov 13, 2013 at 4:56 PM, Junio C Hamano <gitster@pobox.com> wrote: > "Jason St. John" <jstjohn@purdue.edu> writes: > >> Documentation/git-log.txt: >> -- replace single quotes around options/commands with backticks >> -- use single quotes around references to sections >> -- replaced some double quotes with proper AsciiDoc quotes (e.g. >> ``foo'') >> -- use backticks around files and file paths >> -- use title case when referring to section headings >> -- use backticks around option arguments/defaults >> >> Signed-off-by: Jason St. John <jstjohn@purdue.edu> >> --- >> When working on this commit, I noticed a difference in how options and >> option descriptions are separated (e.g. with a blank line or not). At least >> with Vim's syntax highlighting, if there is a blank line between the option >> and its description, the text block is all colored the same; however, if >> there isn't a blank line, then the text block is not specially colored. >> >> Is there an existing convention for how this should be done? > > I do not think we have a written rule or convention (and I do not > know if we want one). While reading the text in the source form > (and the point of choosing AsciiDoc was to be able to read the docs > without formatting), I personally have a slight preference to > immediately follow the body text to the label in the labelled list, > and a blank line after the item, i.e. > > item label:: > This describes the item. > > next item label:: > This describes the next item. > > as it makes it clear that the body belongs to the heading that > precedes it. > > But it does help to have a blank between the label and the beginning > of the body when reflowing the body with fill-paragraph, i.e. > > item label:: > > This describes the item. > > You say that it is also easier on Vim to have the blank line there, > so perhaps we may want to aim for updating the documentation over > time to consistently do so. I dunno. > -- > To unsubscribe from this list: send the line "unsubscribe git" in > the body of a message to majordomo@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html As I stated in my recent resubmit[1], I decided to remove the blank lines after option subheadings because the syntax highlighting in Vim actually looks better with the blank lines removed. As such, I would prefer that we go with the option of removing these blank lines going forward. If we are in agreement on this, should I send in a patch for CodingGuidelines to state this? [1] http://marc.info/?l=git&m=138447927208462&w=2 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH 2/2] Fix minor grammatical and other formatting issues in the "git log" man page 2013-11-15 1:44 ` Jason St. John @ 2013-11-15 1:47 ` Jason St. John 0 siblings, 0 replies; 5+ messages in thread From: Jason St. John @ 2013-11-15 1:47 UTC (permalink / raw) To: git On Thu, Nov 14, 2013 at 8:44 PM, Jason St. John <jstjohn@purdue.edu> wrote: > On Wed, Nov 13, 2013 at 4:56 PM, Junio C Hamano <gitster@pobox.com> wrote: >> "Jason St. John" <jstjohn@purdue.edu> writes: >> >>> Documentation/git-log.txt: >>> -- replace single quotes around options/commands with backticks >>> -- use single quotes around references to sections >>> -- replaced some double quotes with proper AsciiDoc quotes (e.g. >>> ``foo'') >>> -- use backticks around files and file paths >>> -- use title case when referring to section headings >>> -- use backticks around option arguments/defaults >>> >>> Signed-off-by: Jason St. John <jstjohn@purdue.edu> >>> --- >>> When working on this commit, I noticed a difference in how options and >>> option descriptions are separated (e.g. with a blank line or not). At least >>> with Vim's syntax highlighting, if there is a blank line between the option >>> and its description, the text block is all colored the same; however, if >>> there isn't a blank line, then the text block is not specially colored. >>> >>> Is there an existing convention for how this should be done? >> >> I do not think we have a written rule or convention (and I do not >> know if we want one). While reading the text in the source form >> (and the point of choosing AsciiDoc was to be able to read the docs >> without formatting), I personally have a slight preference to >> immediately follow the body text to the label in the labelled list, >> and a blank line after the item, i.e. >> >> item label:: >> This describes the item. >> >> next item label:: >> This describes the next item. >> >> as it makes it clear that the body belongs to the heading that >> precedes it. >> >> But it does help to have a blank between the label and the beginning >> of the body when reflowing the body with fill-paragraph, i.e. >> >> item label:: >> >> This describes the item. >> >> You say that it is also easier on Vim to have the blank line there, >> so perhaps we may want to aim for updating the documentation over >> time to consistently do so. I dunno. >> -- >> To unsubscribe from this list: send the line "unsubscribe git" in >> the body of a message to majordomo@vger.kernel.org >> More majordomo info at http://vger.kernel.org/majordomo-info.html > > As I stated in my recent resubmit[1], I decided to remove the blank > lines after option subheadings because the syntax highlighting in Vim > actually looks better with the blank lines removed. As such, I would > prefer that we go with the option of removing these blank lines going > forward. > > If we are in agreement on this, should I send in a patch for > CodingGuidelines to state this? > > [1] http://marc.info/?l=git&m=138447927208462&w=2 I forgot to mention that if we do go with this, then I will need to resubmit this patch. Sorry for the extra email. ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2013-11-15 1:47 UTC | newest] Thread overview: 5+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2013-11-13 6:21 [PATCH 1/2] Rewrite man page explanation of git log's "--log-size" option Jason St. John 2013-11-13 6:21 ` [PATCH 2/2] Fix minor grammatical and other formatting issues in the "git log" man page Jason St. John 2013-11-13 21:56 ` Junio C Hamano 2013-11-15 1:44 ` Jason St. John 2013-11-15 1:47 ` Jason St. John
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).