Re: [PATCH] submodule documentation: Reorder introductory paragraphs

From: Junio C Hamano <gitster@pobox.com>
Date: May 25, 2015, 22:00 UTC
Message-ID: <xmqqfv6k9v1x.fsf@gitster.dls.corp.google.com>
In-Reply-To: <1432323527-26868-1-git-send-email-sbeller@google.com>

Stefan Beller <sbeller@google.com> writes:

Show 6 quoted lines

>  DESCRIPTION
>  -----------
> +This command will inspect, update and manage submodules.
>  
> +Submodules allow you to keep another Git repository in a subdirectory
> +of your repository. The other repository has its own history,...

The first line somehow bothered me, so I took a random sample of commands I often use:

    git log
       Shows the commit logs.

    git show
       Shows one or more objects (blobs, trees, tags and commits).

    git commit
       Stores the current contents of the index in a new commit along with a
       log message from the user describing the changes.

    git diff
       Show changes between the working tree and the index or a tree, changes
       between the index and a tree, changes between two trees, changes
       between two blob objects, or changes between two files on disk.

    git push
       Updates remote refs using local refs, while sending objects necessary
       to complete the given refs.

I _think_ what bothered me was "This command" (drawing the reaction "eh, what other command are you going to talk about in the help page for this command?"). Perhaps

    Inspects, updates and manages submodules.

may match the style of other help pages better.

On the other hand, I probably would not have felt such a strong "strangeness" if it were described like this:

    This command can help you inspect, update, and manage
    submodules.

I haven't analized it enough to say why it is, but I suspect it has something to do with (my own) perception that "git submodule" is not very essential to do any of these things (i.e. .gitmodules is a very simple text file), but is primarily a helpful wrapper.

The description of "git config", on which I have a similar perception, seem to match ;-)

    git config
       You can query/set/replace/unset options with this command.