git clean --exclude broken?

13 years ago, Todd Rinaldo found that —exclude option is not works with any options, for example, `git clean -Xd -e=foo` to clean the files/folders respect the .gitignore rule except the foo, but in real world, git only respect the git ignore standard rule and not work with -e option.

Today, 13 years later, the problem still exist, so I wonder is this a bug or should we clarify the “correct” usage of exclude in documentation, because it’s really confusing.

The discussion can be viewed by this link: https://git.vger.kernel.narkive.com/ulppacPK/clean-exclude-broken

Looking forward to your reaply!

On 2024-11-24 at 11:10:57, Homyee King wrote:

I don't think this is the right syntax. For example, I did this in my checkout of the Git project:

---- $ touch foo $ git clean -n Would remove foo $ git clean -n -e foo $ git clean -f -e foo $ ls foo foo ----

When you use a short option, you don't specify the equals sign. So you can write `-e foo`, `-efoo`, `--exclude foo`, or `--exclude=foo`. However, `-e=foo` is equivalent to `-e =foo`, which ignores `=foo`.

On 2024-11-26 at 06:13:44, Homyee King wrote:

I don't think there's a command for what you want to do here. You basically want to clear only ignored files, but exclude one pattern from the ignore rules. `-e` doesn't do that: it _adds_ to the ignore rules, not subtracts from them.

So this is what I'd expect to see here with your file structure:

---- % git clean -Xdn -e test.ts Would remove bar/ Would remove foo/ Would remove test.ts ----

since by using `-e`, we've added the additional files to be ignored, and with `-X`, we've said to remove the files.

On 2024-12-09 at 04:53:24, Homyee King wrote:

The `--exclude` option means "exclude this (mark this as ignored) additionally". I agree it could be misinterpreted, but `--include` could as well. The manual page says this about `-e`:

  Use the given exclude pattern in addition to the standard ignore rules
  (see gitignore(5)).

And the text says this about `-x`:

  Don’t use the standard ignore rules (see gitignore(5)), but still use
  the ignore rules given with -e options from the command line. This
  allows removing all untracked files, including build products. This
  can be used (possibly in conjunction with git restore or git reset) to
  create a pristine working directory to test a clean build.

That means that when you say `git clean -xdn -e foo`, Git ignores only `foo`, and says it will remove everything else that would normally be ignored (which is no longer ignored, and thus untracked). Remember that `git clean` only removes untracked files and directories, and `-x` just makes all files normally ignored untracked temporarily for the life of the command. Equivalent text exists in the description section of the manual page.

I don't think this is confusing or that the text is inaccurate, but of course if you want to submit a patch to improve the text, I'm sure we'd be happy to take a look.