From: Jeff King Date: Mon, 13 Apr 2009 11:18:52 GMT Subject: [PATCH 3/5] doc/checkout: refer to git-branch(1) as appropriate Message-ID: <20090413111852.GC15982@coredump.intra.peff.net> In-Reply-To: <20090413110947.GA15647@coredump.intra.peff.net> Most of description for the branch creation options is simply cut and paste from git-branch. There are two reasons to fix this: 1. It can grow stale with respect to what's in "git branch" (which it is now is). 2. It is not just an implementation detail, but rather the desired mental model for the command that we are using "git branch" here. Being explicit about that can help the user understand what is going on. It also makes sense to strip the branch creation options from the synopsis, as they are making it a long, hard-to-read line. They are still easily discovered by reading the options list, and --track is explicitly referenced when branch creation is described. Signed-off-by: Jeff King --- There are two things here that people might disagree with: 1. Referring the user instead of using asciidoc magic to just include the repeated text. While it is nice to save the user the effort of referencing the other documentation, I think sometimes we go too far with this in git. Sometimes it is beneficial for the user not just to get the information, but to have it pointed out that the link exists. Then they can better understand exactly what it is git is doing (it is not "oh, this is a totally unrelated way to create branches" but "this is a convenience wrapper that calls git branch" -- I think the latter is the model we want to use). 2. Shortening the synopsis field. The long lines look awful in the manpage on an 80-column terminal. I don't read git documentation very often, so I have not really noticed, but some of our synopses are quite complex and IMHO unreadable. We are much better off just saying "there are some options, then these 1 or 2 arguments" which give an overview of how you would invoke the command. You can look at the option list if you want to actually see the options. In this patch I just shortened the ones related to branch creation. But I was tempted to take this a step further and get rid of the "-f", "-q", and "-m" options in the synopsis, as well, which I think would look much better. Documentation/git-checkout.txt | 28 +++++++++------------------- 1 files changed, 9 insertions(+), 19 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 16d3c87..22ad10d 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -8,7 +8,7 @@ git-checkout - Checkout a branch or paths to the working tree SYNOPSIS -------- [verse] -'git checkout' [-q] [-f] [-t | --track | --no-track] [-b [-l]] [-m] [] +'git checkout' [-q] [-f] [-m] [-b ] [] 'git checkout' [-f|--ours|--theirs|-m|--conflict=