git@vger.kernel.org mailing list mirror (one of many)
 help / Atom feed
From: Johannes Schindelin <Johannes.Schindelin@gmx.de>
To: Junio C Hamano <gitster@pobox.com>
Cc: Kevin Daudt <me@ikke.info>,
	git@vger.kernel.org, J Wyman <jwyman@microsoft.com>
Subject: Re: [PATCH v2 2/3] for-each-ref: let upstream/push optionally remote ref name
Date: Mon, 16 Oct 2017 13:39:01 +0200 (CEST)
Message-ID: <alpine.DEB.2.21.1.1710161334291.40514@virtualbox> (raw)
In-Reply-To: <xmqqk1zvuahz.fsf@gitster.mtv.corp.google.com>

Hi Junio,

On Mon, 16 Oct 2017, Junio C Hamano wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> >> >> -Also respects `:remotename` to state the name of the *remote* instead of
> >> >> -the ref.
> >> >> +Also respects `:remotename` to state the name of the *remote* instead
> >> >> +of the ref, and `:remoteref` to state the name of the *reference* as
> >> >> +locally known by the remote.
> >> >
> >> > What does "locally known by the remote" mean in this sentence?
> >> 
> >> Good question.  I cannot offhand offer a better and concise
> >> phrasing, but I think can explain what it wants to describe ;-).
> >
> > Yep, described it well.
> >
> > Maybe "and `:remoteref` to state the name by which the remote knows the
> > *reference*"?
> 
> I dunno.  
> 
> The original and your update both seem to come from a worldview
> where there is a single conceptual thing called "reference" that is
> shared between our repository and the remote repository we pull from
> (or push to), and the name we call it is "refs/remotes/origin/devel"
> while the name they use to call it is "refs/heads/devel".  If you
> subscribe to that worldview, then the updated sentence might make it
> clearer than the original.
> 
> But I do not share that worldview, and I am not sure (note: I am
> truly unsure---it's not like I am convinced it is a good idea but
> sugarcoating my expression, at least in this case) if subscribing to
> the worldview helps users' understanding.
> 
> In my view "refs/remotes/origin/devel" is a reference we use to keep
> track of (or "a reference that corresponds to") the reference they
> have called "refs/heads/devel" at the remote, and these are two
> separate entities, so it's not like "this single thing is called
> differently by us and them".
> 
> Stepping back a bit; here is how the description begins.
> 
>     upstream::
>             The name of a local ref which can be considered ``upstream''
>             from the displayed ref.
> 
> So 'upstream' is like 'refs/remotes/origin/devel' in the example in
> the message you are responding to.  Perhaps we can make it clear in
> the description, and then add :remote* modifiers are about asking
> where that remote-tracking branch comes from.  For example, instead
> of these "Also respects...", something like:
> 
>     For a %(upstream) that is a remote-tracking branch, the name of
>     the remote repository it is copied from can be obtained with
>     %(upstream:remotename).  Simiarly, the branch at the remote
>     repository whose tip is copioed to this remote-tracking branch
>     can be obtined with %(upstream:remoteref) as a full refname.
> 
> may reduce the chance of confusion?

Let's take two more steps back.

First, for-each-ref is a low-level command (I do not remember whether our
nickname for "low-level" is "plumbing" or "porcelain" or anything, so I
stick with "low-level" which I deem descriptive enough). That is, users of
this command (and therefore, readers of this man page) need to be quite
familiar with Git's worldview.

Second, the main purpose of this patch series is to answer the question
"what is the default <remoteref> in `git push <remotename>
<ref>:<remoteref>`?" for *many* refs at once.

Maybe it would be better to describe the functionality by describing the
question it tries to answer.

Ciao,
Dscho

  reply index

Thread overview: 31+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-10-02 13:56 [PATCH 0/3] for-each-ref: add :remote-ref and :remote-name specifiers Johannes Schindelin
2017-10-02 13:56 ` [PATCH 1/3] for-each-ref: let upstream/push optionally report the remote name Johannes Schindelin
2017-10-04  7:14   ` Junio C Hamano
2017-10-04  9:08     ` Junio C Hamano
2017-10-05 12:20     ` Johannes Schindelin
2017-10-02 13:57 ` [PATCH 2/3] for-each-ref: let upstream/push optionally report merge name Johannes Schindelin
2017-10-04  9:12   ` Junio C Hamano
2017-10-04 11:41     ` Junio C Hamano
2017-10-05  9:14       ` Junio C Hamano
2017-10-02 13:57 ` [PATCH 3/3] for-each-ref: test :remote-name and :remote-ref Johannes Schindelin
2017-10-05  1:54 ` [PATCH 0/3] for-each-ref: add :remote-ref and :remote-name specifiers Junio C Hamano
2017-10-05 12:19 ` [PATCH v2 0/3] for-each-ref: add :remoteref and :remotename specifiers Johannes Schindelin
2017-10-05 12:19   ` [PATCH v2 1/3] for-each-ref: let upstream/push optionally report the remote name Johannes Schindelin
2017-10-10  9:35     ` Junio C Hamano
2017-10-11  2:07     ` Junio C Hamano
2017-10-05 12:19   ` [PATCH v2 2/3] for-each-ref: let upstream/push optionally remote ref name Johannes Schindelin
2017-10-06  5:10     ` Junio C Hamano
2017-10-11  5:58       ` Junio C Hamano
2017-10-12 19:13         ` Johannes Schindelin
2017-10-13  0:30           ` Junio C Hamano
2017-10-15 16:02             ` Johannes Schindelin
2017-10-13 16:39     ` Kevin Daudt
2017-10-14  2:08       ` Junio C Hamano
2017-10-15 16:05         ` Johannes Schindelin
2017-10-16  1:50           ` Junio C Hamano
2017-10-16 11:39             ` Johannes Schindelin [this message]
2017-10-05 12:19   ` [PATCH v2 3/3] for-each-ref: test :remotename and :remoteref Johannes Schindelin
2017-11-07 16:30   ` [PATCH v3 0/3] for-each-ref: add :remoteref and :remotename specifiers Johannes Schindelin
2017-11-07 16:30     ` [PATCH v3 1/3] for-each-ref: let upstream/push optionally report the remote name Johannes Schindelin
2017-11-07 16:31     ` [PATCH v3 2/3] for-each-ref: let upstream/push report the remote ref name Johannes Schindelin
2017-11-07 16:31     ` [PATCH v3 3/3] for-each-ref: test :remotename and :remoteref Johannes Schindelin
2017-11-08  1:36     ` [PATCH v3 0/3] for-each-ref: add :remoteref and :remotename specifiers Junio C Hamano

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 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.1710161334291.40514@virtualbox \
    --to=johannes.schindelin@gmx.de \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=jwyman@microsoft.com \
    --cc=me@ikke.info \
    /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