Re: PATCH: improve git switch documentation

Martin wrote:

But it's not the same as --new.

If this is an essential part of the previous sentence, it should be part of the sentence:.

  Same [as] the --new option, but allows to use an existing branch name.

But this is wasted space:

  Shouting is the same as talking, but with a different volume.

There's no need for another sentence explaining in what way it is different (higher volume), do it in the same sentence.

What happens when we use an existing branch name?

Except this is a lie. At no point is the branch removed; the branch name is never gone, neither are the commits.

What is actually happening is that the branch head is changed. That is all. And as I already explained in the subthread, everyone understands what changing the branch head does to the branch.

Everyone knows what happens when you reset your computer without saving your Excel spreadsheet. The word "reset" implies loosing state.

If you don't want to use the word "reset", or the term "branch head", then you can say:

  Same as --new, but if the branch already exists it's replaced.

This *still* doesn't explain what it is doing, you would need to read --new.

  Create a new branch like '--new', but if the branch already exists
  it's replaced.

Now it is actually self-contained.

The commits are not lost, they are just not part of this branch anymore. They could easily be part of another branch already.

  Create a new branch like '--new', but if the branch already exists
  it's replaced. The commits that are initially part of the branch might
  not be part of the branch afterwards.

I think the last sentence is superfluous and obvious. Everyone understands that if A is replaced by B, B might be different from A, and thus not everything of A might end up in B.

If you want to send a patch with that unnecessary information, go ahead, what I'm saying is that if the first part is written correctly the last part is obvious.

Cheers.