git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH 1/5] fetch doc: update introductory part for clarity

From
Marc Branchaud <marcnarc@xiplink.com>
Date
May 30, 2014, 19:13 UTC
Message-ID
<5388D857.7010705@xiplink.com>
In-Reply-To
<xmqqioon9msf.fsf@gitster.dls.corp.google.com>
On 14-05-30 01:52 PM, Junio C Hamano wrote:
Show 30 quoted lines
> Marc Branchaud <marcnarc@xiplink.com> writes:
> 
>> On 14-05-29 06:42 PM, Junio C Hamano wrote:
>>> +
>>> +The names of refs that are fetched, together with the object names
>>> +they point at, are written to `.git/FETCH_HEAD`.  This information
>>> +is used by a later merge operation done by 'git merge'.  In addition,
>>
>> Isn't this merge stuff about pull, not fetch?
> 
> It is true that "git pull" uses "git fetch" and .git/FETCH_HEAD is a
> documented mechanism between the two to communicate what commits the
> latter downloaded are to be merged by the former, and that is one of
> the reasons why we had the description here in the original before
> this patch.  A user can also do this to refer to the tip of the
> single branch she fetched:
> 
> 	git fetch origin master
>         git log -p ..FETCH_HEAD
>         git merge FETCH_HEAD
> 
> Perhaps "is used ... by 'git merge'" can be rephrased somehow, like
> "can be used to refer to what was fetched"?  Or we could go in the
> opposite direction and be more explicit, i.e.
> 
> 	"git pull" calls "git fetch" internally, and this
> 	information is used by the former to learn what commits were
> 	fetched by the latter.
> 
> I dunno.

Y'know, I've always been a bit confused by FETCH_HEAD, especially if the fetch updates several remote-tracking branches.

The docs say that all the fetched refs are written to FETCH_HEAD (perhaps a more accurate name would have been FETCH_HEADS?). If that's truly the case, it seems weird to use FETCH_HEAD in log and merge commands. (My FETCH_HEAD file currently has 1434 lines in it -- what does that mean, and what does it imply for those log and merge commands?)

Perhaps FETCH_HEAD shouldn't be mentioned at all in the introductory part of fetch's man page.

		M.
Previous: Junio C HamanoNext: Junio C Hamano
Message 5 of 15 in “Documentation updates for 'git fetch'”
  1. 0/5 Documentation updates for 'git fetch'Junio C Hamano, May 29, 2014
  2. 1/5 fetch doc: update introductory part for clarityJunio C Hamano, May 29, 2014
  3. Marc BranchaudMay 30, 2014
  4. Junio C HamanoMay 30, 2014
  5. Marc BranchaudMay 30, 2014
  6. Junio C HamanoMay 30, 2014
  7. fetch doc: Move FETCH_HEAD material, and add an example.Marc Branchaud, Jun 2, 2014
  8. Junio C HamanoJun 2, 2014
  9. 2/5 fetch doc: update note on '+' in front of the refspecJunio C Hamano, May 29, 2014
  10. Marc BranchaudMay 30, 2014
  11. Junio C HamanoMay 30, 2014
  12. Marc BranchaudJun 2, 2014
  13. 3/5 fetch doc: remove notes on outdated "mixed layout"Junio C Hamano, May 29, 2014
  14. 4/5 fetch doc: on pulling multiple refspecsJunio C Hamano, May 29, 2014
  15. 5/5 fetch doc: update refspec format descriptionJunio C Hamano, May 29, 2014

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.