Stephen & Linda Smith <ischis2@xxxxxxx> writes:
> I think that this is a stale todo.
>
> The only place there is a mention of temporary branches (which is
> then parenthetically called a topic branch) is in relation to how
> Tony Luck organizes his work. Additionally there is already a
> subsection on using a detatched head ("Examining an old version
> without creating a new branch).
I suspect that you stared at the output from "git grep" for
"temporary" or even "temporary branch" and further I suspect that
the experience blinded you.
The two lines in that todo item were first introduced at d5cd5de4
(Documentation: begin discussion of git-remote in user manual,
2007-01-09), and then were updated at b181d57f (user-manual:
reorganize fetch discussion, add internals, etc., 2007-01-27). In
between these two, the lines were rewrapped at 2f99710c
(user-manual: rewrap, fix heading levels, 2007-01-14) but that
commit was purely cosmetic.
When the todo item was introduced, it ended with a full-stop; the
update changed it to a question mark, which I read it as hinting
that the item might not be a good change.
The output from
$ git diff -U40 d5cd5de4 b181d57f Documentation/user-manual.txt
gives us a fairly good answer. When the todo item was introduced,
the "beginning" section was titled "Repositories and Branches", and
showed you how to clone the Linux kernel in its first subsection,
and then the next subsection showed "How to check out a different
version", and showed that "git checkout -b new v2.6.13", followed by
"git reset --hard v2.6.17", are the commands to use for sightseeing
the project's landmarks.
The "new" is used as a temporary branch in the context of that
example; the user is not building anything on top of these commits,
the use of a named branch is ephemeral and the only reason a named
branch is used is because the detached HEAD was a fairly new
invention, introduced at c847f537 (Detached HEAD (experimental),
2007-01-01) and was merged to the mainline at c388761c (Merge branch
'jc/detached-head', 2007-01-11).
After commit b181d57f, aka "Let's keep the todo item for now, but I
am no longer sure if it is a good idea so end it with a question
mark", the "beginning" is a new section called "Git Quick Start",
but the same "git checkout -b new v2.6.15" for sightseeing appears
in this new section.
Another thing to notice is that the "temporary branch" you found in
"git grep" about Tony's workflow did not exist in the user-manual
back in these days. It was added to the user-manual at 9e2163ea
(user-manual: move howto/using-topic-branches into manual,
2007-05-13), so the todo item couldn't possibly have been referring
to that example.
>> > -Simplify beginning by suggesting disconnected head instead of
>> > -temporary branch creation?
>> > -
>>
>> What does "beginning" refer to in this sentence, though?
>
> I had that question too even after looking at the 2007 version of the manual.
>>
>> After a quick reading of the beginning part of the document, I am
>> getting the impression that it refers to the use of the 'new'
>> branch, which is initially created out of v2.6.13 and then later
>> reset to v2.6.17 while the user is in the sightseeing mode. And
>> this way of working _is_ a remnant from the days back when detached
>> HEAD was not with us.
>>
>> It is a completely separate matter if it is a good idea to teach
>> detached HEAD that early in the tutorial, though.
>
> So are you suggesting a move of the section further down?
> Or are you suggesting that that is excised from the manual?
Neither. Because the current text does not teach detached HEAD
early in the tutorial, I see no need to move any section down, or
excising a section.
>> So "remove the task because detached HEAD is a bit too weird
>> thing to learn in that early stage in the learning curve"
>> (i.e. the latter reason) might apply.
>
> Could it be there are two reasons to remove the todo?
There could be, but I do not think it is the case here.
I do not think "it was already done" is a valid reason for removing
this todo item, as I do not think it was done yet.
I think the only possible reason to remove that todo item is because
teaching detached HEAD that early in the user manual gives a bit too
steep learning curve--and I do not disagree with that justification.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html