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

Jeff King wrote:

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.

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

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.

  CONFIGURATION SECTIONS

  We separate the configuration into <...>.

  Core settings

      [core] (see "Core configuration", below)
          <some blurb about core commands here...>

      [user]
          Default identity to attribute new commits to.

      [url "baseaddress"] (see git-remote(1))
          Short names to use for a long, frequently-used URL.

      [alias] (see "Aliases")
          User-defined git commands that alias other git commands
          with options.

      [gc] (see git-gc(1))
          Automatic repository repacking settings.

      [http] (see git-remote-http(1))
          Tweaking HTTP transport behavior.

      [i18n] (see git-commit(1))
          Commit log encoding and display encoding.

      [notes]
      [notes "rewrite"] (see git-notes(1))
          Display and propagation of commit notes.

      [rerere] (see git-rerere(1))
          Whether to save successful merge resolutions for later
          reuse.

  Output format

      [advice] (see "Advice Options")
          Whether to display optional help messages that may
          dwarf regular output.

      [color] (see "Colored output")
          Which commands should use colored output.

      [color "gitcommand"] (see "Colored output")
          What colors to use for a particular sort of output.  The
          relevant command name is generally the most prominent git
          command which produces that output.

      [format] (see git-log(1))
	  How to display commit metadata by default.  This section is
          shared with git-format-patch(1) configuration.

      [pager] (see "Paginated output")
          Which commands should paginate their output.

  Repository setup

      [branch "branchname"] (see git-branch(1))
          Where `git pull` should pull from for each local branch.

      [remote "reponame"] (see git-remote(1))
          URL and branches for a named remote repository.

      [remotes] (see git-remote(1))
          User-defined collections of remote repositories that are
          often fetched from or pushed to together.

  Helper programs

      [web] (see git-help(1))
          Web browser to use for 'git help --web' and 'git instaweb'.

      [merge "mergedriver"] (see gitattributes(5))
          Low-level format-specific helper for merging files.

      [browser "webbrowser"] (see git-web-browse(1))
          How to invoke a given web browser.

      [man "manpager"] (see git-help(1))
          How to invoke a given man pager.

      [difftool "diffvisualizer"] (see git-difftool(1))
          How to invoke a given diff frontend.

      [mergetool "mergeresolver"] (see git-mergetool(1))
          How to invoke a given interactive 3-way merge helper.

      [guitool "guihelper"] (see git-gui(1))
          How git gui should invoke this helper when selected from
          the "Tools" menu.

  Default behavior of commands

      [add]		git-add(1)
      [am]		git-am(1)
      [apply]		git-apply(1)
      [branch]		git-branch(1)
      [clean]		git-clean(1)
      [commit]		git-commit(1)
      [diff]		git-diff(1)
      [difftool]	git-difftool(1)
      [fetch]		git-fetch-pack(1), git-fetch(1), git-pull(1)
      [format]		git-format-patch(1), git-log(1)
      [gc]		git-gc(1)
      [gitcvs]		git-cvsserver(1)
      [gui]		git-gui(1)
      [help]		git-help(1), git --help
      [imap]		git-imap-send(1)
      [init]		git-init(1)
      [instaweb]	git-instaweb(1)
      [interactive]	git-add--interactive(1), git add -i
      [log]		git-log(1), git-show(1), git-whatchanged(1)
      [mailmap]		git-shortlog(1)
      [man]		git-help(1)
      [merge]		git-merge(1), git-mergetool(1)
      [mergetool]	git-mergetool(1)
      [notes]		git-notes(1)
      [pack]		git-gc(1), git-repack(1)
      [pull]		git-pull(1)
      [push]		git-push(1)
      [receive]		git-receive-pack(1)
      [repack]		git-repack(1)
      [sendemail]	git-send-email(1)
      [sendemail "profile"]
			git-send-email(1)
      [showbranch]	git-show-branch(1)
      [status]		git-status(1)
      [tar]		git-archive(1)
      [transfer]	git-fetch-pack(1), git-receive-pack(1)