diff --git a/doc/bugs/add__58___inconsistently_treats_files_in_dotdirs_as_dotfiles.mdwn b/doc/bugs/add__58___inconsistently_treats_files_in_dotdirs_as_dotfiles.mdwn new file mode 100644 index 0000000000..353fbdd1dd --- /dev/null +++ b/doc/bugs/add__58___inconsistently_treats_files_in_dotdirs_as_dotfiles.mdwn @@ -0,0 +1,103 @@ +This is an upstream resubmission of [Debian bug #959506](https://bugs.debian.org/959506). + +### Please describe the problem. + +As of v8, git-annex divides files into “large” and “non-large” files, the +former of which are supposed to be automatically added to the annex and the +latter to vanilla git when running `git annex add`. git-annex uses the +configuration option `annex.largefiles`, a file matching expression, to +categorize files as “large”; all other files end up as “non-large”. + +Furthermore, git-annex always treats “dotfiles” as “non-large”, without +consulting `annex.largefiles`. Setting the configuration option +`annex.dotfiles` (false by default) makes git-annex use `annex.largefiles` +to also categorize “dotfiles”. + +The manual never defines which files are considered “dotfiles”, therefore +I am assuming a definition of “a dotfile is a non-directory file whose +basename begins with an ASCII period”. git-annex however will treat any file +in any directory as a dotfile – i.e., it will ignore `annex.largefiles` and +always add the file to vanilla git, unless `annex.dotfiles` is set to true +– as long as the relative pathname to the file begins with an ASCII period, +e.g. `.foo/bar.txt` (which is *not* a dotfile according to the assumed +definition above). git-annex will further cease treating the same file as +a dotfile if the relative pathname no longer begins with an ASCII period, +e.g. because the working directory has been changed. + +I expect git-annex to distinguish between dotfiles and non-dotfiles solely +by looking at the file's basename, even if the relative path to the file +begins with a dot. I also expect `annex.dotfiles` to have no influence +whatsoever on files whose basename doesn't begin with an ASCII period, even +if the containing directory does. git-annex's *actual* behavior is highly +counter-intuitive to the notion that being a dotfile is a property of the +file's (base-)name. Due to the lack of definition of dotfiles in the manual, +it is unclear to me whether this is intended (but in my opinion quirky) +behavior, or rather a bug. + +### What steps will reproduce the problem? + +1. Set up a repository for use with git-annex. Leave `annex.dotfiles` at + its default value (`false`), and `annex.largefiles` unset. + +2. Create files `bar1`, `bar2` and `bar3` within a directory `.foo`. What + matters is that `.foo` begins with a period, `bar1` etc. don't. + +3. Run `git annex add .foo/bar1`. git-annex will have forced the file into + vanilla git as a “non-large” file, because it is recognized as + a “dotfile”. But `bar1` is not a dotfile because it does not begin with + a period. + +4. (Optional.) Set `annex.dotfiles` to `true` and run `git annex add + .foo/bar2`. The file is added to the annex. In conjunction with step 3, + this shows that git-annex really does apply the `annex.dotfiles` setting + to files such as `.foo/bar2`, even if they aren't “dotfiles” because the + file basenames don't start with a period. + +5. (Optional.) Set `annex.dotfiles` back to false, change directory to + `.foo`, then run `git annex add bar3`. The file will be added to the + annex, as it is no longer recognized as a dotfile. This shows that + git-annex's behavior is inconsistent: the same file is either seen as + a dotfile or not, depending on which directory git-annex is run from and + what the resulting relative pathnames look like. + +### What version of git-annex are you using? On what operating system? + +git-annex v8.20200330, on Debian sid, as of 2020-05-08 + +### Please provide any additional information below. + +[[!format sh """ +$ cd /tmp/git-annex-dotfiles +$ git init +Initialized empty Git repository in /tmp/git-annex-dotfiles/.git/ +$ git annex init +init (scanning for unlocked files...) +ok +(recording state in git...) +$ mkdir .foo +$ echo a > .foo/bar1 +$ echo b > .foo/bar2 +$ echo c > .foo/bar3 +$ git annex add .foo/bar1 # I expect this to be added to the annex, but no +add .foo/bar1 (non-large file; adding content to git repository) ok +(recording state in git...) +$ git config annex.dotfiles true +$ git annex add .foo/bar2 # clearly affected by annex.dotfiles +add .foo/bar2 +ok +(recording state in git...) +$ git config annex.dotfiles false +$ cd .foo +$ git annex add bar3 # clearly affected by the exact relative pathname +add bar3 +ok +(recording state in git...) +"""]] + +### Have you had any luck using git-annex before? (Sometimes we get tired of reading bug reports all day and a lil' positive end note does wonders) + +Yes. git-annex has been in use on my end for a couple of years, and it is my +go-to solution for “want something versioned, but can't store the +contents themselves (too big, too sensitive, etc.)?”. Furthermore, git-annex +documentation in general is excellent. But that is also why I'm stumped that +the manual is so silent on this point.