added adjusted_branches design doc, meets at least 2 different needs

1 files changed, 54 insertions, 0 deletions

diff --git a/doc/design/adjusted_branches.mdwn b/doc/design/adjusted_branches.mdwn
new file mode 100644
index 000000000..9ea93ee72
--- /dev/null
+++ b/doc/design/adjusted_branches.mdwn
@@ -0,0 +1,54 @@
+Consider two use cases:
+
+1. Using a v6 repo with locked files on a crippled filesystem not
+   supporting symlinks. For the files to be usable, they need to be
+   unlocked. But, the user may not want to unlock the files everywhere,
+   just on this one crippled system.
+2. [[todo/hide_missing_files]]
+
+Both of these could be met by making `git-annex sync` maintain an adjusted
+version of the HEAD branch. This could be a detached HEAD or a branch named
+eg `adjusted/master`.
+
+There would be a filter function. For #1 above it would simply convert all
+annex symlinks to annex file pointers. For #2 above it would omit files
+whose content is not currently in the annex.
+
+When merging changes from a remote, apply the filter to the head of the
+remote branch, and merge the result.
+
+When objects are added/removed from the annex, the associated file has to
+be looked up, and the filter applied to it. So, dropping a file with the
+missing file filter would cause it to be removed from the adjusted branch,
+and receiving a file's content would cause it to appear in the adjusted
+branch.
+
+When committing changes, the filter has to be reversed somehow. The
+commit is fed through the reversing filter to get a commit that should be
+the same as if the branch had not been adjusted. This needs to be done by
+the pre-commit hook, so that the user can run `git commit`, if possible.
+It would be annoying if only `git-annex sync` made such commits.
+
+The reverse-filtered commit becomes the new tip of the master branch, and
+so can be pushed out to remotes. The adjusted/master branch is not pushed
+to remotes. `git-annex sync` should automatically push master when
+adjusted/master is checked out.
+
+Note that reversing filter #1 would mean only converting pointer files to
+symlinks when the file was originally a symlink. This is problimatic when a
+file is renamed. Would it be ok, if foo is renamed to bar and bar is
+committed, for it to be committed as an unlocked file, even if foo was
+originally locked?
+
+## problems
+
+Using `git checkout` when in an adjusted branch is problimatic, because a
+non-adjusted branch would then be checked out. But, we can just say, if
+you want to get into an adjusted branch, you have to run some command.
+
+Tags are bit of a problem. If the user tags an ajusted branch, the tag
+includes the local adjustments.
+
+Running `git push` when in adjusted/master won't push anything
+(with "matching" push strategy). Users may find that surprising.
+Users of `git-annex sync` won't need to worry about it though.