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

Re: [PATCH 6/8] Documentation/notes: simplify treatment of default display refs

From
Jeff King <peff@peff.net>
Date
May 10, 2010, 06:06 UTC
Message-ID
<20100510060630.GC13340@coredump.intra.peff.net>
In-Reply-To
<20100509084325.GA9801@progeny.tock>
On Sun, May 09, 2010 at 03:43:25AM -0500, Jonathan Nieder wrote:
Show 6 quoted lines
> Thanks for bringing this up.  I think some of the changes ultimately
> ought to be propagated back to config.txt.  I copied the text anyway
> because as long as the differences are in short-term memory, I find it
> easier to manipulate two similar files than one file with ifdefs in
> it; so it seemed like a reasonable strategy to let these diverge for a
> few weeks and then merge them with ifdefs again.

Hrm. If that merge actually happens while things are still in short-term memory. ;)

> Some divergence is needed imho so that the text can say things like
> “see the Options section earlier in this page”.

Yeah, understandable. And I also don't want to get into a rat's nest of ifdefs in the documentation. Which is why I was pushing to move straight into something more elegant. :)

Show 7 quoted lines
> Longer term, I suspect I would like a gitconfig.5 page that functioned
> something like the main commands list, which could avoid some
> duplication.  But this is something to be considered carefully: right
> now it is very easy to start with knowing there is some configuration
> for what you want to change (conflict hunk format, say) and find it by
> searching the descriptions in git-config.1; if we split that file up,
> that won’t be so easy.

Yeah, I do worry about people being able to search effectively. But to some degree, sensible naming of the options helps with that. Searching for "conflict" even in just a list of options should come up with "merge.conflictstyle", and I had always intended for such a gitconfig.5 to have a full list.

>   CONFIGURATION SECTIONS
>   [...]

Your breakdown looks like a sensible thing to have at the start of gitconfig.5. It looks like you were planning on putting some generic concepts like "alias" and "core" into that page (at the end of the overview list), and then referring to individual command pages for their respective sections. That sounds reasonable to me.

-Peff
Previous: Jonathan NiederNext: Jonathan Nieder
Message 14 of 21 in “filling out the notes man page”
  1. 0/8 filling out the notes man pageJonathan Nieder, May 9, 2010
  2. 1/8 Documentation/notes: document format of notes treesJonathan Nieder, May 9, 2010
  3. Jeff KingMay 9, 2010
  4. 2/8 Documentation/notes: describe content of notes blobsJonathan Nieder, May 9, 2010
  5. 3/8 Documentation/notes: add configuration sectionJonathan Nieder, May 9, 2010
  6. 4/8 Documentation/notes: simplify treatment of default notes refJonathan Nieder, May 9, 2010
  7. Thomas RastMay 12, 2010
  8. Jonathan NiederMay 12, 2010
  9. 5/8 Documentation/log: add a CONFIGURATION sectionJonathan Nieder, May 9, 2010
  10. Jeff KingMay 9, 2010
  11. 6/8 Documentation/notes: simplify treatment of default display refsJonathan Nieder, May 9, 2010
  12. Jeff KingMay 9, 2010
  13. Jonathan NiederMay 9, 2010
  14. Jeff KingMay 10, 2010
  15. Jonathan NiederMay 12, 2010
  16. Jeff KingMay 12, 2010
  17. 7/8 Documentation/notes: clean up description of rewriting configurationJonathan Nieder, May 9, 2010
  18. 8/8 Documentation/notes: nitpicksJonathan Nieder, May 9, 2010
  19. Johan HerlandMay 10, 2010
  20. Thomas RastMay 12, 2010
  21. Documentation/notes: fill out the man page a littleJonathan Nieder, May 12, 2010

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.