Subject: RE: Git feature request: Option to force Git to abort a checkout if working directory is dirty (i.e. disregarding the check for conflicts)

From: "Jonas Bang" <[email-masked]>
Date: Sat, 29 Mar 2014 12:49:47 +0100

Thanks for your feedback, Junio, I have added more details and tried to simplify the request.

> "Jonas Bang" <[email-masked]> writes:
> 
> > Hi Git developers,
> >
> > This is my first Git feature request, I hope it won’t get me hanged on
> > the gallows ;o)
> >
> > *Git feature request:*
> > Add an option to Git config to configure the criteria for when a "git
> > checkout" should abort.
> >
> > *Name proposal and options:*
> > checkout.clean false <default>
> > checkout.clean true
> 
> A configuration variable without command line override will make the system
> unusable.  When thinking about a new feature, please make it a habit to first
> add a command line option and then if that option turns out to be useful in
> the real world (not in the imaginary world in which you had such a feature,
> where even you haven't lived in yet), then think about also adding
> configuration variables to control the default.

Proposal for "git checkout" command line option:
--clean false|true|include-untracked|all

If the 'false' option is used then 'git checkout' will work as today. This should be the default behavior and it is not needed to use this command line option, nor set the configuration variable. The need for the '--clean false' option is if the configuration variable is set to 'true', ' include-untracked' or 'all' in global or local config then it is possible to override this configuration from command line by using '--clean false'.

If the 'true' option is used then 'git checkout' will abort if the index or the working tree differs from HEAD.

If the 'include-untracked' option is used then 'git checkout' will abort if there are any untracked files, or if the index or the working tree differs from HEAD.

If the 'all' option is used then 'git checkout' will abort if there are any ignored files added, or if there are any untracked files, or if the index or the working tree differs from HEAD.

Proposal is also to add this as a configuration variable (e.g. checkout.clean false|true|include-untracked|all), as the usecase is most relevant for people using 3rd party IDE or GUI which calls the standard "git checkout" command.

> Also, a useful definition of "clean"-ness may have to change over time as we
> gain experience with the feature.  And also as a user personally gains
> experience with using Git.  It is somewhat implausible that a boolean
> true/false may remain sufficient.

I have added more options to specify more precisely the definition of "clean"-ness.
 
> > *False behavior:*
> 
> What is "false"?
> 
> Ah, when the configuration is set to "false", which will be the default?

Yes, exactly, this was what I meant.

> > As is:
> > When doing a checkout then Git will check if your working directory is
> > dirty, and if so check if the checkout will result in any conflicts,
> > and if so abort the checkout with a message:
> >
> > $ git checkout some_branch
> > error: Your local changes to the following files would be overwritten
> > by
> > checkout:
> >        some_file
> > Please, commit your changes or stash them before you can switch branches.
> > Aborting
> >
> > If no conflicts then:
> >
> > $ git checkout some_branch
> > M       some_file
> > M       some_other_file
> > Switched to branch 'some_branch'
> >
> > I.e. it will only abort if there are conflicts.
> 
> Sensible.  This is the behaviour that is very often depended upon by people
> who use Git with multiple branches.  Are you thinking about changing it in
> any way when the new configuration is set to "false", or is the above just a
> summary of what happens in the current system?

This was just meant as a summary.

> > *True behavior:*
> > When doing a checkout then Git will check if your working directory is
> > dirty (checking for both modified and added untracked files), and if
> > so abort the checkout with a message:

This will in fact be the 'include-untracked' option where all untracked files are also checked in addition to the index and the working tree.

> > $ git checkout some_branch
> > error: Your working directory is not clean.
> > Please, commit your changes or stash them before you can switch branches.
> > Aborting
> >
> > I.e. it will abort if working directory is dirty (checking for both
> > modified and added untracked files).
> > I.e. you can only do checkout if you get "nothing to commit, working
> > directory clean" when running "git status" (ignoring ignored files though).
> 
> The above two say very different things.  For some people, having many
> throw away untracked files is a norm that they do not consider it is even
> worth their time to list them in .gitignore and they do not want to be
> reminded in "git status" output, and the latter definition of
> "checkout.clean=true will kill checkout when status says there are some
> things that could be committed" would suit them, while the former definition
> "checkout.clean=true will kill checkout when there is any untracked files"
> would be totally useless.

Regarding those who has many throw away untracked files, they can either not change the configuration (i.e. keep the 'git checkout' functionality as it is), or optionally use the 'true' option which only checks the index and the working tree (i.e. not checking on untracked files).

> So I can understand the latter, but I do not see how the former could be a
> useful addition.

By changing my original behavior of 'true', and by adding 'include-untracked' and 'all', I believe I have taken into account the scenarios you describe.

> For some people it is also a norm to keep files that have been modified from
> HEAD and/or index without committing for a long time (e.g. earlier, Linus said
> that the version in Makefile is updated and kept modified in the working tree
> long before a new release is committed with that change).  The default
> behaviour would cover their use case so your proposal would not hurt them,
> but I wonder if there are things you could do to help them as well, perhaps
> by allowing this new configuration to express something like "local changes in
> these paths are except from this new check".

Yes, those people would probably use the default 'false' behavior as it is already. If they however would like to use e.g. the 'true' or 'include-untracked' setting as a configuration variable, then they can use the command line option 'false' if they wish to do a 'git checkout' even with modified files in the working tree.