stack clean should be more thorough by default

[simonmichael]

Several times I have been caught out by expecting stack clean to reset state and fix some transient failure, then finding out that only removing the .stack-work directories was sufficient. And I have only just now discovered stack clean --full. In the most recent example two of us spent several hours troubleshooting weird NFData version-skew-ish doctest failures on one machine, which stack clean did not fix. Somewhat related: #2278, #2936 and #3152.

We were using stack 1.6.3 (and recent HEAD in my case). I don't know how to reproduce the failure state. I expected clean to reset state and be pretty much equivalent to starting with fresh clone of the project. Instead the doctest failures persisted until we tried a fresh clone (and then remembered to try manually removing .stack-work). clean's --full flag was not obvious.

[mgsloan]

Makes sense to me. In favor of deprecating --full, and adding a flag to instead just use cabal clean.

[adrianwong]

Stupid question: with this enhancement, will stack clean fail if cabal is not already on PATH?

[mgsloan]

@adrianwong Nope, the cabal command is the cabal-install package / executable, which stack only uses for solver and building ghcjs. The usage of cabal for cleaning is instead using the compiled Setup.hs. For simple build types, the Setup.hs is a simple invocation of a function in the Cabal library. So, in a way there are two different libraries / executables that are both called "cabal", and stack mostly just uses the lower level one, called Cabal.

[vanceism7]

I can try my hand at this one if no one else is doing it yet

[vanceism7]

Hey @mgsloan, do you mean to just add a warning in the cli when the --full flag is used, and adding a new flag like --shallow? Or should I add a new clean command which actually does a full clean by default (In addition to the deprecated warnings)?

[mgsloan]

@vanceism7 I believe I meant the latter - that clean would do --full by default, and some other flag cause it to do cabal cleans.

It is possible that might not be an expected behavior change. Perhaps it would be safer to require specifying either --shallow (or some other name) or --full. Perhaps @mihaimaruseac , @snoyberg , or some other maintainer has an opinion on what to do here?

[dbaynard]

The behaviour of --full is more like a purge. If the concern is changing existing behaviour, then introducing stack purge as a synonym for stack clean --full would help. In particular, as a new command, it would be listed alongside clean and would make clear that clean doesn't clear everything.

It is still not clear from the docs what stack clean means — would it be accurate to say the following?

stack clean

Delete the local working directories containing compiler output. e.g. …

Use stack clean <specific-package> to delete the output for package specific-package only.

stack purge

Delete the local stack working directory, including extra-deps, git dependencies and the compiler output. Does not delete any snapshot packages, compilers or installed programs.

Also

stack/src/Stack/Clean.hs

Line 57 in ac2c759

-- ^ Delete the "dist directories" as defined in 'Stack.Constants.distRelativeDir'

should point to Stack.Constants.Config.distRelativeDir.

[vanceism7]

Yea, the main issue I was thinking about is preserving backward compatibility. But I think in general it makes sense to use a stack purge command/synonym instead of changing the default behavior of clean. From my experience with other systems (such as dotnet cli), clean only deletes any files generated in a build, it doesn't clear out the entire bin folder. I'll add stack purge and see what I can do to make the documentation a little clearer. Thanks for the input everyone!

[dbaynard]

@simonmichael Would you please confirm that this would resolve your issue?

[simonmichael]

Hi @dbaynard, I think:

• stack purge would be an improvement on stack clean --full (more discoverable)
• but I don't think adding yet another command is optimal
• I can't see all the implications for existing workflows, and I don't know the exact costs of doing a full clean, but clean means clean - I think doing a full clean is the better default. If half-cleaning is a useful operation, that could be the optional mode (clean --light). Ideally speaking.
• it would be good to see the exact behaviour of the two modes spelled out, your doc draft above is a good start but not yet clear.
• two reasons to do a clean are: 1. to reset to a known state, for predictable builds and to drive out ghosts; 2. to reclaim disk space. I think 1 is the more important. For this, cleaning things which can affect build operations are the priority. Other artifacts like binaries, perhaps less so.

[simonmichael]

After rereading this, I'll qualify: my first three points are debatable, perhaps. I'm more confident about the last two. But my main desires are:

• preventing/fixing state-related build problems should be easy, discoverable, and default
• unnecessarily complicated commands and options should be avoided

If half-cleaning remains the default, printing a note explaining what was cleaned and how to clean more thoroughly could be another option.

[ygale]

Our team uses stack all day for working on a large project with a lot of dependencies. We occasionally need to do rm -rf .stack-work, but it is painful.

We expect stack clean to do the same thing that clean does for every other build tool I know - remove the build artifacts and cause all modules within the local project to be rebuilt. We do not need an alias for rm -fr .stack-work; we can type that ourselves. It's OK if that is provided, similar to "distclean" in other build tools, but it would be a surprising default for stack clean.

Others may have different preferences. The world won't come to an end for us if we are outvoted and stack clean is changed to be like distclean instead of clean. I think the biggest issue here is poor documentation #2278, as mentioned by @simonmichael.

[dbaynard]

• 1. to reset to a known state, for predictable builds and to drive out ghosts;

This is what stack clean by itself will do, by deleting the build artefacts.

See #4480 for further discussion.

We do not need an alias for rm -fr .stack-work; we can type that ourselves.

There are multiple .stack-work directories for a project, and the clean command ought to handle them.

None of this discussion concerns issues with shared artefacts, e.g. snapshot dependencies. clean currently does nothing for any ghosts there.