git@vger.kernel.org mailing list mirror (one of many)
 help / 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)
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 index

Thread overview: 32+ messages in thread (expand / 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]
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 publically 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 to all the recipients 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

git@vger.kernel.org mailing list mirror (one of many)

Archives are clonable:
	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.org/gmane.comp.version-control.git

 note: .onion URLs require Tor: https://www.torproject.org/
       or Tor2web: https://www.tor2web.org/

AGPL code for this site: git clone https://public-inbox.org/ public-inbox