Skip to contentSkip to conversation

Documentation Directions

DISCUSSION Jon Loeliger 3 participants 4 messages Jun 15, 2016

lore
Share & tools
lore
#0 lore raw

Couple of questions regarding documentation direction:

- Is the plan to update all docs to use $GIT_DIR instead of .git?

- Do we intend on adding explicit support for '--help' on most, if not all, of the git commands? In some cases (git-branch) a -*) case tacitly catches --help and usage()'s it. In other cases (git-pull) this can't be done as -*) passes options on to git-fetch. I think that we should catch --help directly so that it doesn't emit git-fetch's *) catch-all usage:

    % git pull --help
    usage: git-fetch-pack [-q] [-v] [--exec=upload-pack] [host:]directory <refs>...
    Fetch failure: --help

- Do you want to head in the per-man-page-"Now What?" direction as suggested by Junio?

Thanks,
jdl

#1 lore raw
Quoted 1 line · Jon Loeliger

- Is the plan to update all docs to use $GIT_DIR instead of .git?

Well, shouldn't we go all the way and use ${GIT_DIR:-.git} then? :-)

nikolai

Signature · 3 lines
Nikolai Weibull: now available free of charge at http://bitwi.se/!
Born in Chicago, IL USA; currently residing in Gothenburg, Sweden.
main(){printf(&linux["\021%six\012\0"],(linux)["have"]+"fun"-97);}
#2 lore raw
In reply to Jon Loeliger
Quoted 3 lines · Jon Loeliger

Couple of questions regarding documentation direction:

- Is the plan to update all docs to use $GIT_DIR instead of .git?

I personally feel we should use less (not more) $GIT_DIR in the documentation and casual mention of things under .git/ directory should say .git/ instead, with the understanding that the reader have already learned that there is a way to override it if the user chooses to do so.

Quoted 2 lines

- Do we intend on adding explicit support for '--help' on most, if not all, of the git commands?

I think that would be very helpful.

Quoted 2 lines

- Do you want to standardize on using a '$' prompt for all the example command executions samples?

Ah, I see you recently added a couple of Csh style '%' prompt. Also I suspect that some examples in earlier tutorial do not even have any prompt.

You are right -- being consistent would be nice.

#3 lore raw
In reply to Jon Loeliger

Also:

- Do you want to standardize on using a '$' prompt for all the example command executions samples? Like so:

Do do the thing, run the command:

$ git-frobnicate --weirdly

Do you/we care? Consistency uber alles?

Thanks,
jdl