Hi Junio, On Mon, 16 Oct 2017, Junio C Hamano wrote: > Johannes Schindelin <Johannes.Schindelin@xxxxxx> 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
