Re: ghost refs

On Thu, Apr 08, 2010 at 01:42:01PM -0700, Junio C Hamano wrote:

I would also like to have consensus on this, too. But it seems like it gets bikeshedded to death every time it comes up. But hey, why not try it one more time? :)

Yep, makes sense.

I much prefer to have the "major modes of operation". So yes, "command [<options>] <args>" is useless. But

  git log [<option>] [<since>..<until>] [[--] <path>...]

is sparse but useful. You immediately get a sense of how to invoke the command, and it is very readable. If you were to put in the dozens of possible options, it would become hard to see what it is saying. If you want a complete list of options (IMHO), they should be in list form.

As another example, for git-branch, I would suggest:

  git branch [<options>]
  git branch [<options>] <branchname> <start-point>
  git branch -m [<oldbranch>] <newbranch>
  git branch -d [<options>] <branchname>

creating a new branch, moving a branch, and deleting a branch. I would also be happy if each mode was explicitly described. Some of my favorite synopses are those of perl modules, which tend to give you a very short and readable code snippet of how you might use the module, along with comments showing anything non-obvious.

In the case of branch, enumerating the options in the synopsis doesn't bother me much, because there are few enough that it remains fairly readable. But something something like "git format-patch" or "git apply" are getting pretty long.

I know that others disagree, though. When this came up last time, some people said they really like having that giant clump of options. Our manpages currently seem to be split between the two types.

Definitely.

Yes. Also, it should probably discuss the different modes of operation if there is more than one.

I also prefer sorting by functionality. The only reason to prefer alphabetical is for people finding a specific option. Presumably their pager has a search function (whereas for grouping by functionality, I agree with your conciseness argument, and it means you are more likely to find related options that might help you).

I would really prefer most of this material to be pushed out into its own manual pages, and referred to by name (e.g., say "see githistory(7) for a discussion of history simplification" or "history is simplified as described in githistory(7)").

Here's my reasoning. There is a lot of overlap in git commands. The same concepts come up in many places (e.g., revision traversal, formatting, and diff options in log, show, whatchanged, diff, diff-*, etc). History simplification will come up in at least rev-list and log. So our options are:

  1. choose one place as the canonical location, and say "see history
     simplification in git-log(1)" everywhere else.

     This is annoying because the user has to find the right section in
     git-log. For manpages, it would be nicer to just do "man
     githistory", and for formats with hyperlinks, it should be a
     hyperlink.

  2. factor it out into history.txt, and include it in each relevant
     page. This is what we do with pretty-formats.txt, diff-options, and
     some others.

     My problem with this approach is two-fold:

       a. There is some value to naming the concept to the user. If I
          read the "git show" page and then the "git log" page, I may
          see that they both have pretty options. But it takes some
          mental effort to see that they are identical and then reduce
          it to "both commands take the same pretty options" in my mind.
          But if we explicitly link, then we are saying "there is a
          concept called pretty options. You can use it here, and when
          you see other places mention that concept, it is the same
          thing." Which IMHO makes git easier to learn for new users;
          they learn easily digestable concepts and build on them
          instead of being overwhelmed with commands and options.

        b. As an experienced user who already knows that "pretty
           formats" is a concept, I find it annoying to have to find
           them inside of git-log(1) when I want to see them. I would
           much prefer to do "man gitpretty".

        c. These subsegments can get long. pretty-formats.txt is 186
           lines. That is a big chunk to be in my way if I am reading
           git-log(1). I get to the "pretty formats" section and say
           "that is not interesting to me. What is the next section?"
           and then have to scroll down through 186 lines.

  3. factor it into githistory(7), and reference it by name

     Obviously this is my favorite. :) It does have one downside,
     though. If we convert pretty-formats.txt into gitpretty(7), then
     searching for "oneline" in git-log may not turn up what you want.
     I wonder if we can summarize with something like:

       --format=:
       --pretty=<oneline|full|raw>:
       --oneline:
         Format the output. See gitpretty(7).

    in git-log(1).

Yes, examples are good.

Agreed. I find them useless at best, clutter at worst.

You didn't mention configuration variables. I do think it would be better to have the variables for a specific command in that command's manpage (in an ENVIRONMENT section that also mentions environment variables). For variables that affect many commands, I would suggest factoring them out as described above.

git-config (or perhaps even gitconfig(7)) should have a list of all variables and where they are described, like:

  apply.ignorewhitespace        git-apply(1)
  apply.whitespace              git-apply(1)
  branch.autosetupmerge         git-branch(1)
  [etc]

There is not much point in having full descriptions in one giant list. Instead, you can peruse the whole list, and then go to the configuration section of the relevant manpage to see a bunch of related options. Such a list should be pretty easy to generate automatically from the other documentation.

-Peff