docs for git-annex adjust

5 files changed, 71 insertions, 0 deletions

diff --git a/debian/changelog b/debian/changelog
index eed11e4f8..62caa20d1 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,5 +1,7 @@
 git-annex (6.20160319) UNRELEASED; urgency=medium
 
+  * adjust --unlock: Enters an adjusted branch in which all annexed files
+    are unlocked. The v6 equivilant of direct mode, but much cleaner!
   * ddar remote: fix ssh calls
     Thanks, Robie Basak
 
diff --git a/doc/git-annex-adjust.mdwn b/doc/git-annex-adjust.mdwn
new file mode 100644
index 000000000..551eabe01
--- /dev/null
+++ b/doc/git-annex-adjust.mdwn
@@ -0,0 +1,50 @@
+# NAME
+
+git-annex adjust - enter an adjusted branch
+
+# SYNOPSIS
+
+git annex adjust --unlock`
+
+# DESCRIPTION
+
+Enters an adjusted form of the current branch. The annexed files will
+be treated differently. For example with --unlock all annexed files will
+be unlocked.
+
+The adjusted branch will have a name like "adjusted/master(unlocked)".
+Since it's a regular git branch, you can use `git checkout` to switch
+back to the original branch at any time.
+
+While in the adjusted branch, you can use git-annex and git commands as
+usual. Any commits that you make will initially only be made to the
+adjusted branch. 
+
+To propigate changes from the adjusted branch back to the original branch,
+and to other repositories, as well as to merge in changes from other
+repositories, use `git annex sync`.
+
+This command can only be used in a v6 git-annex repository.
+
+# OPTIONS
+
+* `--unlock`
+
+  Unlock all annexed files in the adjusted branch. This allows
+  annexed files to be modified.
+
+# SEE ALSO
+
+[[git-annex]](1)
+
+[[git-annex-unlock]](1)
+
+[[git-annex-upgrade]](1)
+
+[[git-annex-sync]](1)
+
+# AUTHOR
+
+Joey Hess <id@joeyh.name>
+
+Warning: Automatically converted into a man page by mdwn2man. Edit with care.
diff --git a/doc/git-annex-direct.mdwn b/doc/git-annex-direct.mdwn
index 3cade1a8c..c3d7dfadc 100644
--- a/doc/git-annex-direct.mdwn
+++ b/doc/git-annex-direct.mdwn
@@ -20,6 +20,8 @@ commands.
 Note that the direct mode/indirect mode distinction is removed in v6
 git-annex repositories. In such a repository, you can
 use [[git-annex-unlock]](1) to make a file's content be directly present.
+You can also use [[git-annex-adjust]](1) to enter a branch where all
+annexed files are unlocked, which is similar to the old direct mode.
 
 # SEE ALSO
 
@@ -29,6 +31,8 @@ use [[git-annex-unlock]](1) to make a file's content be directly present.
 
 [[git-annex-unlock]](1)
 
+[[git-annex-adjust]](1)
+
 # AUTHOR
 
 Joey Hess <id@joeyh.name>
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 6830f741f..e9698c169 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -295,6 +295,13 @@ subdirectories).
   
   See [[git-annex-indirect]](1) for details.
 
+* `adjust`
+
+  Switches a repository to use an adjusted branch, which can automatically
+  unlock all files, etc.
+  
+  See [[git-annex-adjust]](1) for details.
+
 # REPOSITORY MAINTENANCE COMMANDS
 
 * `fsck [path ...]`
diff --git a/doc/tips/unlocked_files.mdwn b/doc/tips/unlocked_files.mdwn
index fd103940e..cc9972f9e 100644
--- a/doc/tips/unlocked_files.mdwn
+++ b/doc/tips/unlocked_files.mdwn
@@ -95,6 +95,8 @@ mode is used. To make them always use unlocked mode, run:
 `git config annex.addunlocked true`
 """]]
 
+## mixing locked and unlocked files
+
 A v6 repository can contain both locked and unlocked files. You can switch 
 a file back and forth using the `git annex lock` and `git annex unlock`
 commands. This changes what's stored in git between a git-annex symlink
@@ -102,6 +104,12 @@ commands. This changes what's stored in git between a git-annex symlink
 the repository in locked mode, use `git annex add`; to add a file in
 unlocked mode, use `git add`.
 
+If you want to mostly keep files locked, but be able to locally switch
+to having them all unlocked, you can do so using `git annex adjust
+--unlock`. See [[git-annex-adjust]] for details. This is particularly
+useful when using filesystems like FAT, and OS's like Windows that don't
+support symlinks.
+
 ## using less disk space
 
 Unlocked files are handy, but they have one significant disadvantage