Re: git switch --force vs --discard-changes: docs don't match behavior

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

David Mandelberg <david@mandelberg.org> writes:

> $ touch Makefile

You'd need to explain this example a bit better.  The reproduction
must be done in a repository where the master branch has Makefile
tracked, you are not on the master branch, and the commit you have
checked out does not have Makefile tracked.  IOW, this is not making
Makefile stat-dirty, but is creating a new untracked file.

As I wasted a few minutes scratching my head before figuring out the
above, I'm leaving a note for others.

> $ git switch master
> error: The following untracked working tree files would be overwritten
> by checkout:
>         Makefile
> Please move or remove them before you switch branches.
> Aborting

Makes sense (note.  I do not use "git switch" myself).

> $ git switch --discard-changes master
> error: Untracked working tree file 'Makefile' would be overwritten by merge.

I would guess that this "discard changes" takes the word "change" in
a reasonbly strict sense (note.  I do not use "git switch" myself,
"git checkout" does not have this option, and I do not recall
thinking about how "--discard-changes" should operate when the
feature was added, so this is pretty much my first time to think
about this issue).  Untracked "Makefile", by definition, is not
known by Git, so it cannot even tell if it was changed or not.

If "Makefile" is tracked in the current commit, this would have
discarded changes from that modified file and allowed you to switch
to the master branch.

> $ git switch --force master
> branch 'master' set up to track 'origin/master'.
> Switched to a new branch 'master'

And forcing would give us the same behaviour as "checkout -f".

> Is this a bug in the code or documentation?

I do not have a strong opinion either way.  It may appear to some
users that giving a finer grained control is a merit.  Even when you
are willing to throw away changes to already tracked content,
getting stopped when you may lose a totally untracked thing might be
nicer.

On the other hand, I suspect to many others this finer grained
control does not give much value while adding more confusion.

I am obviously biased because I am accustomed not to have this
distinction and accept "checkout -f" as a reasonable way to force
switching to another branch discarding any and all local
modifications including untracked new files that get in the way,
though.  But I do not feel strongly enough to say that the behaviour
and the feature itself is misguided and we should rip it out.  As
long as that "finer grained control" is working in a consistent and
explainable way, I'd actually vote for fixing the documentation to
explain how "--discard-changes" is a bit milder than "--force'.

Thanks.