git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH] git-rebase.txt: use back-ticks consistently

From
Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date
Jun 28, 2022, 10:22 UTC
Message-ID
<220628.86k091f5fy.gmgdl@evledraar.gmail.com>
In-Reply-To
<pull.1270.git.1656364861242.gitgitgadget@gmail.com>
On Mon, Jun 27 2022, Derrick Stolee via GitGitGadget wrote:
> From: Derrick Stolee <derrickstolee@github.com>
This looks 99% good, but...
Show 22 quoted lines
> While inspecting the 'git rebase' documentation, I noticed that it is
> inconsistent with how it uses back-ticks (or other punctuation) for
> identifying Git commands, command-line arguments, or values for those
> arguments.
>
> Sometimes, an argument (like '--interactive') would appear without any
> punctuation, causing the argument to not have any special formatting.
> Other times, arguments or 'git rebase' itself would have single-quotes
> giving a bold look (in the HTML documentation at least).
>
> By consistently using back-ticks, these types of strings appear in a
> monospace font with special highlighting to appear more clearly as text
> that exists in a command-line invocation of a Git command.
>
> This rather-large diff is the result of scanning git-rebase.txt and
> adding back-ticks as appropriate. Some are adding back-ticks where there
> was no punctuation. Others are replacing single quotes.
>
> There are also a few minor cleanups in the process, such as one place
> that did not use tabs for the first paragraph in a bulletted list.
> Another case still referred to the dashed form, but it was the only use
> in the file except for the heading and NAME section.

I think the commit message should speak more matter-of-factly & briefly, i.e. just "change so and so...".

Show 23 quoted lines
>     While I noticed this inconsistency when looking at git rebase as part of
>     the git rebase --update-refs work, I didn't know the best way to update
>     the document from start to finish.
>     
>     This giant update is probably not the best way to present the change.
>     
>     I can see splitting it up in a few ways, but I wanted to check to first
>     see if that was necessary. If it is, then here are the strategies I
>     considered:
>     
>      1. Focus on type of update. This would mean a change for adding
>         back-ticks on all --<option> text, adding back-ticks on all "git
>         rebase" instances, adding back-ticks on things like <upstream>, and
>         doing other types of changes like whitespace updates or "git-rebase"
>         to "git rebase".
>     
>      2. Focus on the section of the document. This would limit the diff by
>         the section size, such as OPTIONS or the discussion on the backends.
>     
>      3. Focus on the edits that most-recently edited these lines. Doing some
>         scripting, I was able to construct this date-sorted list of previous
>         edits (by diffing the git blame output before and after this
>         change). The most-recent changes before this are:
I think this is fine, but I want to recommend doc-diff in your toolkit,
e.g.:
	
	$ Documentation/doc-diff HEAD~ HEAD -- -U0|cat
	diff --git a/e4a4b31577c7419497ac30cebe30d755b97752c5/home/avar/share/man/man1/git-rebase.1 b/e37244faa0a730bb930dac4e10d8eed4af682a5d/home/avar/share/man/man1/git-rebase.1
	index 91ccda823b2..41dfbee38a4 100644
	--- a/e4a4b31577c7419497ac30cebe30d755b97752c5/home/avar/share/man/man1/git-rebase.1
	+++ b/e37244faa0a730bb930dac4e10d8eed4af682a5d/home/avar/share/man/man1/git-rebase.1
	@@ -489,2 +489,2 @@ OPTIONS
	-           Append "exec <cmd>" after each line creating a commit in the final
	-           history. <cmd> will be interpreted as one or more shell commands.
	+           Append exec <cmd> after each line creating a commit in the final
	+           history.  <cmd> will be interpreted as one or more shell commands.
	@@ -502 +502 @@ OPTIONS
	-           If --autosquash is used, "exec" lines will not be appended for the
	+           If --autosquash is used, exec lines will not be appended for the
	@@ -880 +880 @@ NOTES
	-       When the git-rebase command is run, it will first execute a
	+       When the git rebase command is run, it will first execute a

I see Phillip spotted some of this already, but the "exec" change here looks unwanted, i.e. let's use double quotes there.

For the last hunk I'd think just:
    When rebase is run, it will...
Would be briefer & better in that case.

I also see that we have other spots in our wider docs where we use the dashed form, I'm fine with converting this case, but maybe better to leave it aside to make this only a ``-quotation change, or to split up this & the whitespace & other things you mentioned into another commit.

Any way you're OK with is fine with me, thanks for fixing these.
Previous: Derrick StoleeNext: Derrick Stolee
Message 4 of 19 in “git-rebase.txt: use back-ticks consistently”
  1. git-rebase.txt: use back-ticks consistentlyDerrick Stolee via GitGitGadget, Jun 27, 2022
  2. Phillip WoodJun 28, 2022
  3. Derrick StoleeJun 28, 2022
  4. Ævar Arnfjörð BjarmasonJun 28, 2022
  5. Rendering back-ticks in plaintext docs (was Re: [PATCH] git-rebase.txt: use back-ticks consistently)Derrick Stolee, Jun 28, 2022
  6. Junio C HamanoJun 28, 2022
  7. Junio C HamanoJun 28, 2022
  8. Derrick StoleeJun 28, 2022
  9. git-rebase.txt: use back-ticks consistentlyDerrick Stolee via GitGitGadget, Jun 28, 2022
  10. Junio C HamanoJun 28, 2022
  11. Phillip WoodJun 29, 2022
  12. Derrick StoleeJun 29, 2022
  13. Junio C HamanoJun 30, 2022
  14. Derrick StoleeJun 29, 2022
  15. Phillip WoodJun 29, 2022
  16. Derrick StoleeJun 29, 2022
  17. git-rebase.txt: use back-ticks consistentlyDerrick Stolee via GitGitGadget, Jun 29, 2022
  18. Phillip WoodJun 29, 2022
  19. Junio C HamanoJun 30, 2022

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.