Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

[Andrew Ardill <andrew.ardill@gmail.com>]

On 18 December 2012 08:59, Junio C Hamano <gitster@pobox.com> wrote:
> Andrew Ardill <andrew.ardill@gmail.com> writes:
>> Even if the primary purpose of "git checkout <branch>" is to "check
>> out the branch so that further work is done on that branch", I don't
>> believe that means it has to be stated first. In fact, I would say
>> that there are enough other use cases that the language should be
>> slightly more use-case agnostic in the first situation. For example,
>> someone might switch to another branch or commit simply to see what
>> state the tree was in at that point.
>
> I've been deliberately avoiding the term "switch", actually.  I
> agree that it may be familiar to people with prior exposure to
> subversion, but that is not the primary audience of the manual.

I don't have much experience with svn, so I didn't make that
connection. Independent of svn usage, what is wrong with the term
'switch'?

I would be interested to hear how translators communicate the checkout
concept, as I assume the word checkout doesn't exist in many
languages. For me, switching between revisions is a natural way of
phrasing the action, but perhaps there is a better way of saying the
same thing?

>> Some people use checkout to
>> deploy a tag of the working tree onto a production server. The first
>> example in particular is, I think, a common enough operation that
>> restricting the opening lines of documentation to talking about
>> building further work is misleading.
>
> I agree with you that sightseeing use case where you do not intend
> to make any commit is also important.  That is exactly why I said
> "further work is done on that branch" not "to that branch" in the
> message you are responding to.

Ah ok, I didn't pick up on that nuance. Your suggestion from earlier
has, for example, "Prepare to work on building new history on
<branch>" which *is* excluding that use case. Perhaps modifying
similar lines to something like "Prepare to work with the
repository/history/something from <branch>" or maybe just "Prepare to
work with <branch>" would better encapsulate those use cases.
Following lines would expand on what it means to work with a branch or
commit, and the technical details of updates to the repositories
current state.

Regards,

Andrew Ardill