Web lists-archives.com

Re: Git documentation on branching.




On Mon, Apr 10, 2017 at 12:45 PM, Samuel Åslund <samuel@xxxxxxxxxxxx> wrote:
> On 17/4/10 12:21, Ævar Arnfjörð Bjarmason wrote:
>>
>> On Mon, Apr 10, 2017 at 8:56 AM, Samuel Åslund <samuel@xxxxxxxxxxxx>
>> wrote:
>>>
>>> Hi all.
>>>
>>> I just started playing around with branching in git.
>>> I have been using it more or less as Subversion until now.
>>>
>>> One feature with "git branch xyz" and "git checkout xyz" that is rather
>>> obvious if you know them but bit me a little since I did not, is that
>>> uncommitted work in progress is not affected or saved when switching
>>> between
>>> branches. Thus I cleaned up the directory when working with the branch
>>> and
>>> now I'm trying to find a stash where I hopefully have a copy of those
>>> files.
>>>
>>> Would it be possible to add something in the documentation to warn others
>>> that uncommitted work is not saved or affected by branching?
>>
>>
>> The main UI in git for switching branches is "git checkout", and it's
>> mentioned in the second paragraph of the documentation:
>>
>> "[when switching branches] local modifications to the files in the
>> working tree are kept, so that they can be committed to the
>> <branch>.".
>>
>> Did you read this and find it unclear, and if so can you elaborate on
>> what the confusion was, maybe we can fix the docs with that in mind?
>>
>> Or did you read some entirely different docs (what docs?) where we're
>> perhaps not mentioning this as prominently?
>
>
> No, I did not read the git checkout manpage.
> When I googled "git branch" I got the two pages mentioned below and this
> one:
> Git - Basic Branching and Merging
> https://git-scm.com/.../Git-Branching-Basic-Branching-and-Mer...

This list doesn't maintain that book, it looks like the right place to
file bugs & improvement suggestions in it is
https://github.com/progit/progit2

It might be an issue with the git-scm site though that issues in the
book aren't funneled there instead of here. How did you go from
noticing an issue in the book to contacting this mailing list? Maybe
we need to update some page involved in that.

> I find that mostly manpages require some context before they are useful so I
> go for the more wordy pages when trying to get my head around something new.
> Neither of the three top-hits on google included the local modifications
> comment where I noticed it. An actual search for that string right now does
> not find anything either.

Yeah but unfortunately we can do little about that stuff, we just
maintain the man pages.

> The comment you refer to in the git checkout man-page is probably enough
> heads-up for someone who knows git reasonably well, I do not know if it
> would have made me realize exactly how the feature works.
> I'm not even sure I know how "local modifications" is defined in Git
> terminology, does it include "(un)staged changes", and or untracked files?

Maybe we should say "uncommitted modifications" there. I think
starting to talk about staged & unstaged might just invite similar
confusion.

It's hard to say anything in these docs without being inaccurate or
losing the audience :(

> Thanks for the attention.
>
>
>>> The first two hits on my google search was very informative about
>>> branching
>>> but I did not see that specific nugget of information (I might have been
>>> careless reading, but if I did not see it others will probably also miss
>>> it).
>>>
>>> Git - git-branch Documentation
>>> https://git-scm.com/docs/git-branch
>>>
>>> Git - Branches in a Nutshell
>>> https://git-scm.com/book/.../Git-Branching-Branches-in-a-Nutsh...
>>>
>>> This is my first try to contribute to the Git community, I hope it will
>>> be
>>> useful to somebody.
>>>
>>> Regards,
>>> //Samuel
>
>