[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
