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

A list of things missing or wrong in the documentation

From
NWNikolai Weibull <mailing-lists.git@rawuncut.elitemail.org>
Date
Dec 6, 2005, 22:12 UTC
Message-ID
<20051206221252.GA8839@puritan.petwork>

Here's a list of things that are missing, wrong, or badly formatted in the documentation (all checked against the man pages):

git-checkout-index:
        SYNOPSIS:
                --index
                --quiet
                --force
                --all
                --no-create
                (How do we put these in the SYNOPSIS?)
                (My bad, forgot to mention this in an earlier patch.)
git-read-tree:
        --trivial
        SYNOPSIS:
                --reset
git-update-index:
        -h
        --help
        (perhaps redundant)
git-rev-list:
        --dense
        --no-merges
git-merge-base:
        -a, --all
git-verify-pack:
        --
git-http-fetch:
        commit-id and url are missing descriptions
git-update-server-info:
        -f
git-am:
        --utf8 is converted to -u
        --keep is converted to -k
git-bisect:
        Documentation is messed up.  Lines are being joined when they
        shouldn't be (put "+ " at end of line).
git-cherry-pick:
        --no-commit
        --replay
git-clone:
        SYNOPSIS:
                --local
                --shared
                --quiet
                --upload-pack
git-commit:
        --all
        --signoff
        --verify
        --no-verify
        --edit
        -n
git-diff:
        --diff-options should be <common diff options>
        The table isn't rendered properly in the man-page.  I'm guessing
        that this is a problem with my DocBook templates, but I wanted
        to check if anyone else has this issue.
git-format-patch:
        SYNOPSIS:
                provide spacing around options, like other man-pages
        --keep-subject
        --numbered
        --output-directory
        -h --help
        -m
        -d
git-ls-remote:
        -h
        -t
        
git-pull:
        --strategy
git-repack:
        -n
        -l
git-revert:
        --no-commit
        -r --replay
git-show-branch:
        --topo-order
git-cvsimport:
        error in spacing (-P)
git-prune:
        --
git-tag:
        doesn't follow the format of the other manual pages
        missing explicit documentation for many options
General:
        The term "commit-id" isn't listed in the glossary.  Should this
        be changed to "commit" instead?
        Style guides generally suggest putting a comma after "e.g." and
        "i.e.", i.e., "e.g.," and "i.e.,".  It's perhaps a bit anal, but
        what do you think?
        rev is used as a term in some places.  Should perhaps expand it
        to revision?

I should of course provide patches for this, but I'm quite a bit under the weather at the moment, and as a 1.0.0 release draws near I figured that it'd be best that people at least know what I know so that they may do something about it. (Also, someone with better knowledge of asciidoc and git itself would probably do a better job than I could.)

        nikolai
-- 
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);}
Message 1 of 1 in “A list of things missing or wrong in the documentation”
  1. Nikolai WeibullDec 6, 2005

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.