Re: [PATCH 01/11] git-parse-remote: fix highly misleading man page

From: Stefan Beller <sbeller@google.com>
Date: May 11, 2017, 17:21 UTC
Message-ID: <CAGZ79kb57HzJQ4VLFD_NMKvEnriPVXoAAPimg6BG_Z+PPjJ4aQ@mail.gmail.com>
In-Reply-To: <b26882e61ef466c787b575d3fd60bfeec8a9281a.1494509599.git.johannes.schindelin@gmx.de>

On Thu, May 11, 2017 at 6:47 AM, Johannes Schindelin <johannes.schindelin@gmx.de> wrote:

Show 22 quoted lines

> The man page still talked about the .git/remotes/ directory (which is no
> longer in use, as of 75c384efb52 (Do not create $GIT_DIR/remotes/
> directory anymore., 2006-12-19)).
>
> Let's just revamp it almost completely to reflect the *purpose* of that
> scriptlet, as opposed to its implementation details.
>
> Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
> ---
>  Documentation/git-parse-remote.txt | 7 +++----
>  1 file changed, 3 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/git-parse-remote.txt b/Documentation/git-parse-remote.txt
> index a45ea1ece81..7f865f33898 100644
> --- a/Documentation/git-parse-remote.txt
> +++ b/Documentation/git-parse-remote.txt
> @@ -3,7 +3,7 @@ git-parse-remote(1)
>
>  NAME
>  ----
> -git-parse-remote - Routines to help parsing remote repository access parameters
> +git-parse-remote - Routines to help parsing remote repository information

Today I learned about git-parse-remote. Upon further inspection it is just a lib, not anything useful for a user. (The man page with or without this patch is not very helpful to me)

Only git-rebase as well as git-submodule include this lib, the submodules only need get_default_remote (4 lines of sh), which is also available in the submodule--helper, we'd just have to expose it and make it accessible.

I wonder if we'd want to retire this script in the long run.

I also wonder if rewriting the man page is good use of (your) time, as the last contribution specifically to Documentation/git-parse-remote.txt is 62d955fd43 (parse-remote: remove unused functions, 2009-06-12), which has been a while since.

The outline in the coverletter promised more than just rewording, but I am fine with the change as is; it's a good start.

Thanks, Stefan