Re: [PATCH] Add a reference to gitk localbranc remote/branch in gittutorial

[Junio C Hamano <gitster@pobox.com>]

"Paolo Ciarrocchi" <paolo.ciarrocchi@gmail.com> writes:

> On 8/25/08, Junio C Hamano <gitster@pobox.com> wrote:
>> Eric Raible <raible@gmail.com> writes:
>>
>>> Paolo Ciarrocchi <paolo.ciarrocchi <at> gmail.com> writes:
>>>
>>>> +Alice can also use gitk to browse that Bob did:
>>>
>>> s/that/what/ ?
>>>
>>>> +------------------------------------------------
>>>> +alice$ gitk master origin/master
>>>> +------------------------------------------------
>>>
>>> I think that you meant:
>>>
>>> alice$ gitk master..origin/master
>>
>> I'd suggest rewording the explanation to have Alice "compare what both of
>> them did", not just "browse what Bob did".
> ...
>> And for that purpose, I think the original form used by Paolo's patch is
>> the most appropriate here in an early part of the tutorial, as it teaches
>> how to view full histories leading to the tips of these two branches.
>
> well, it might be a good idea to mention both.
>
> do you think we should add a note about git log --graph as well?

"Probably yes" and "not here".

>> Earlier in the tutorial sequence we teach "gitk" without any parameter to
>> view the history of the current branch, and here the user learns one new
>> thing, to view more than just the current branch.
> ...
>> Limiting the output with "..origin/master" (or "...origin/master") can be
>> taught after demonstrating this most basic form.

With the existing flow, I would actually suggest you not to use
origin/master at all.  The example before you inserted your changes does
not update origin/master.

	Alice can use gitk to compare what both of them did:

	$ gitk HEAD FETCH_HEAD

then teach the limiting:

	Notice unlike the earlier example that you used gitk to view the
	history leading to current status, this shows both histories
	leading to Alice's current state (HEAD) and the state you just
	fetched from Bob (FETCH_HEAD).  You can limit what is shown by
	using revision range notation:

        $ gitk HEAD..FETCH_HEAD

	Two commits written with two dots in between means "show
	everything that is reachable from the latter but excluding
	anything that is reachable from the former".  Alice already knows
	what she did well, as well as what she and Bob started working on,
	and she is only interested in what Bob did since their histories
	forked, working independently.

	By the way, the notation "git log -p ..FETCH_HEAD" you saw
	earlier is a short-hand for "git log -p HEAD..FETCH_HEAD".  HEAD,
	that means your current state, can be dropped on either side of
	the two-dot range notation.

It might be better to remove the last paragraph, and instead explain the
meaning of "..FETCH_HEAD" notation immediately after "git log -p" was used
to "fetch-review-but-not-integrate" description (i.e. before the part your
patch touched).

If you want to, you can also teach three-dot form after showing how to use
the two-dot form.

	Alice may want to view what both of them did since they forked.
	She can use three-dot form instead of the two-dot form:

        $ gitk HEAD...FETCH_HEAD

	This means "show everything that is reachable from either one, but
	exclude anything that is reachable from both of them".

	Again, note that these range notation can be used with both gitk
	and "git log".