git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Johannes Schindelin <Johannes.Schindelin@gmx.de>
To: Stefan Beller <sbeller@google.com>
Cc: "git@vger.kernel.org" <git@vger.kernel.org>,
	Junio C Hamano <gitster@pobox.com>
Subject: Re: [PATCH 01/11] git-parse-remote: fix highly misleading man page
Date: Thu, 11 May 2017 21:14:52 +0200 (CEST)	[thread overview]
Message-ID: <alpine.DEB.2.21.1.1705112109410.146734@virtualbox> (raw)
In-Reply-To: <CAGZ79kb57HzJQ4VLFD_NMKvEnriPVXoAAPimg6BG_Z+PPjJ4aQ@mail.gmail.com>

Hi Stefan,


On Thu, 11 May 2017, Stefan Beller wrote:

> On Thu, May 11, 2017 at 6:47 AM, Johannes Schindelin
> <johannes.schindelin@gmx.de> wrote:
> > 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)

Yes, I figured as much when I read the man page. It shows how much most of
our man pages of the olden days improved when you find an unchanged one...

> 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 do not think that we can. Just like git-sh-setup, we advertised it for
use in custom scripts.

> 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.

1) we still advertise those "shell library files" for consumption in
   users' scripts, so I think we have to keep the man page, too, and

2) The fact that the man page is stale just shows how dearly it is in need
   of being edited, no? ;-)

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

You mean the commit message (I do not think I talked about the
git-parse-remote man page in the cover letter)?

If so, I think I only promised to completely revamp it and to stop talking
about implementation details...

Ciao,
Dscho

  reply	other threads:[~2017-05-11 19:15 UTC|newest]

Thread overview: 62+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-05-11 13:47 [PATCH 00/11] Start retiring .git/remotes/ and .git/branches/ for good Johannes Schindelin
2017-05-11 13:47 ` [PATCH 01/11] git-parse-remote: fix highly misleading man page Johannes Schindelin
2017-05-11 17:21   ` Stefan Beller
2017-05-11 19:14     ` Johannes Schindelin [this message]
2020-11-11 15:17     ` [PATCH 0/5] Remove now-unused git-parse-remote Ævar Arnfjörð Bjarmason
2020-11-11 17:37       ` Jeff King
2020-11-11 19:29         ` Junio C Hamano
2020-11-12 14:09         ` Ævar Arnfjörð Bjarmason
2020-11-12 18:42           ` Jeff King
2020-11-12 14:19       ` How do I "git fetch" with a custom <refspec> but a default remote? Ævar Arnfjörð Bjarmason
2020-11-12 18:51         ` Jeff King
2020-11-12 19:26           ` Chris Torek
2020-11-12 20:48             ` Jeff King
2020-11-12 21:22               ` Junio C Hamano
2020-11-14 12:12         ` Ævar Arnfjörð Bjarmason
2020-11-11 15:17     ` [PATCH 1/5] parse-remote: remove unused GIT_DIR variable Ævar Arnfjörð Bjarmason
2020-11-11 15:17     ` [PATCH 2/5] parse-remote: remove long-dead rebase code Ævar Arnfjörð Bjarmason
2020-11-11 15:17     ` [PATCH 3/5] parse-remote: remove long-dead git-pull.sh code Ævar Arnfjörð Bjarmason
2020-11-11 15:17     ` [PATCH 4/5] parse-remote: move used code to git-submodule.sh Ævar Arnfjörð Bjarmason
2020-11-11 15:17     ` [PATCH 5/5] parse-remote: remove this now-unused library Ævar Arnfjörð Bjarmason
2020-11-11 16:33       ` Junio C Hamano
2020-11-12 20:31         ` [PATCH v2 0/2] Retire git-parse-remote Junio C Hamano
2020-11-12 20:31           ` [PATCH v2 1/2] parse-remote: move used code to git-submodule.sh Junio C Hamano
2020-11-12 20:31           ` [PATCH v2 2/2] parse-remote: remove this now-unused library Junio C Hamano
2020-11-12 20:49           ` [PATCH v2 0/2] Retire git-parse-remote Jeff King
2020-11-12 21:25             ` Junio C Hamano
2020-11-13  9:42           ` Ævar Arnfjörð Bjarmason
2020-11-14 12:21           ` [PATCH v3 0/3] submodule sh->C & retire parse-remote Ævar Arnfjörð Bjarmason
2020-11-14 12:21           ` [PATCH v3 1/3] submodule: use "fetch" logic instead of custom remote discovery Ævar Arnfjörð Bjarmason
2020-11-16 21:13             ` Junio C Hamano
2020-11-14 12:21           ` [PATCH v3 2/3] submodule: remove sh function in favor of helper Ævar Arnfjörð Bjarmason
2020-11-14 12:21           ` [PATCH v3 3/3] parse-remote: remove this now-unused library Ævar Arnfjörð Bjarmason
2020-11-16 21:19             ` Junio C Hamano
2020-11-17 14:24               ` Ævar Arnfjörð Bjarmason
2017-05-11 13:47 ` [PATCH 02/11] Documentation: really deprecate .git/remotes/ and .git/branches/ Johannes Schindelin
2017-05-11 13:47 ` [PATCH 03/11] remote: warn loud and clear when .git/branches/ is *still* used Johannes Schindelin
2017-05-11 13:47 ` [PATCH 04/11] remote: warn loud and clear when .git/remotes/ " Johannes Schindelin
2017-05-11 13:47 ` [PATCH 05/11] Revert "Revert "Don't create the $GIT_DIR/branches directory on init"" Johannes Schindelin
2017-05-11 17:26   ` Stefan Beller
2017-05-11 13:47 ` [PATCH 06/11] PREVIEW: t5510: convert .git/remotes/ test to use a regular remote Johannes Schindelin
2017-05-11 13:47 ` [PATCH 07/11] PREVIEW: t5516: stop testing .git/branches/ functionality Johannes Schindelin
2017-05-11 13:47 ` [PATCH 08/11] PREVIEW: remote: remove support for migrating ancient remotes Johannes Schindelin
2017-05-11 13:48 ` [PATCH 09/11] PREVIEW: t5515: remove .git/remotes/ and .git/branches/ tests Johannes Schindelin
2017-05-11 13:48 ` [PATCH 10/11] PREVIEW: t0060: stop testing support for .git/remotes/ and .git/branches/ Johannes Schindelin
2017-05-11 13:48 ` [PATCH 11/11] PREVIEW: remove " Johannes Schindelin
2017-05-11 18:19   ` Stefan Beller
2017-05-11 19:19     ` Johannes Schindelin
2017-05-12  1:14 ` [PATCH 00/11] Start retiring .git/remotes/ and .git/branches/ for good Junio C Hamano
2017-05-12 10:18   ` Johannes Schindelin
2017-05-16  0:37     ` Junio C Hamano
2017-05-16  8:05       ` Ævar Arnfjörð Bjarmason
2017-05-16  9:06         ` Junio C Hamano
2017-05-16 10:02           ` Ævar Arnfjörð Bjarmason
2017-05-17  0:51             ` Junio C Hamano
2017-05-12 12:00   ` Junio C Hamano
2017-05-12 14:19     ` Johannes Schindelin
2017-05-12 17:38       ` Jonathan Nieder
2017-05-13 10:13         ` Junio C Hamano
2017-05-12 21:11       ` Junio C Hamano
2017-05-15  8:42         ` Johannes Schindelin
2017-05-12  9:11 ` Jeff King
2017-05-12 11:09   ` Johannes Schindelin

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=alpine.DEB.2.21.1.1705112109410.146734@virtualbox \
    --to=johannes.schindelin@gmx.de \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=sbeller@google.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).