[RFC] Define "precious" attribute and support it in `git clean`

From: Sebastian Thiel <sebastian.thiel@icloud.com>
Date: Oct 10, 2023, 12:37 UTC
Message-ID: <79901E6C-9839-4AB2-9360-9EBCA1AAE549@icloud.com>

[Note: I'm collaborating with Josh Triplett (CCed) on the design.]

I'd like to propose adding a new standard gitattribute "precious". I've included proposed documentation at the end of this mail, and I'm happy to write the code. I wanted to get feedback on the concept first.

What's a 'precious' file?

"Precious" files are files that are specific to a user or local configuration and thus not tracked by Git. As such, a user spent time to create or generate them, and to tune them to fit their needs. They are typically also ignored by `git` due to `.gitignore` configuration, preventing them to be tracked by accident.

This proposal suggests to make them known to Git using git-attributes so that `git clean` can be taught to treat them with care.

Example: A Linux Kernel .config file

Users can mark the `.config` file as 'precious' using `.gitattributes`:

    /.config precious

When checking which ignored files `git clean -nx` would remove, we would see the following.

    Would remove precious .config
    Would remove scripts/basic/.fixdep.cmd
    Would remove scripts/basic/fixdep
    Would remove scripts/kconfig/.conf.cmd

This highlights precious files by calling them out, but doesn't change the behaviour of existing flags. Instead, the new flag `-p` is added which lets `git clean` spare precious files.

Thus `git clean -np` would print:

    Would remove scripts/basic/.fixdep.cmd
    Would remove scripts/basic/fixdep
    Would remove scripts/kconfig/.conf.cmd

The precious file is not part of the set of files to be removed anymore.

`git clean -[n|f] -xp` will fail with an error indicating that `-x` and `-p` are mutually exclusive. The hope is that people can replace some of their usage of `-x` with `-p` to preserve precious files, while continuing to use `-x` if they want a completely clean working directory.

Additional Benefits

`git clean -fdp` can now be used to restore the user's directory to a pristine post-clone state while keeping all files and directories the project or user identifies as precious. There is less fear of accidentally deleting files which are required for local development or otherwise represent a time investment.

Example: A precious IDE configuration directory.

To keep IDE configuration, one can also mark entire directories - the following could go into a user-specific gitattributes file denoted by the `core.attributesFile` configuration.

    /.idea/** precious

With this attributes file in place, `git clean -ndx` would produce the following output...

    Would remove .DS_Store
    Would remove precious .idea/

...while `git clean -ndp` would look like this:

    Would remove .DS_Store

Here's a patch showing what the documentation could look like. Happy to write the corresponding code.

---

diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 5e1a3d5148..5b2eab6573 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -60,6 +60,10 @@ OPTIONS
 	Use the given exclude pattern in addition to the standard ignore rules
 	(see linkgit:gitignore[5]).
 
+-p::
+	Remove ignored files as well (like `-x`), but preserve "precious"
+	files (see linkgit:gitattributes[5]).
+
 -x::
 	Don't use the standard ignore rules (see linkgit:gitignore[5]), but
 	still use the ignore rules given with `-e` options from the command
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 6deb89a296..f68aadc3c2 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -1248,6 +1248,20 @@ If this attribute is not set or has an invalid value, the value of the
 (See linkgit:git-config[1]).
 
 
+Preserving precious files
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`precious`
+^^^^^^^^^^
+
+A file marked as `precious` will be preserved when running linkgit:git-clean[1]
+with the `-p` option. Use this attribute for files such as a Linux kernel
+`.config` file, which are not tracked by git because they contain user-specific
+or build-specific configuration, but which contain valuable information that a
+user spent time and effort to create.
+
+
+
 USING MACRO ATTRIBUTES
 ----------------------
 

What do you think?

Thanks for your feedback,
Sebastian