4 files changed, 107 insertions, 3 deletions
diff --git a/doc/design/assistant/desymlink.mdwn b/doc/design/assistant/desymlink.mdwn
index 457d7268d..48d307920 100644
--- a/doc/design/assistant/desymlink.mdwn
+++ b/doc/design/assistant/desymlink.mdwn
@@ -43,11 +43,12 @@ is converted to a real file when it becomes present.
 
 ## concrete design
 
-* Enable with annex.nosymlink or such config option.
-* Use .git/ for the git repo, but `.git/annex/objects` won't be used.
+* Enable with annex.direct
+* Use .git/ for the git repo, but `.git/annex/objects` won't be used
+  for object storage.
 * `git status` and similar will show all files as type changed, and
   `git commit` would be a very bad idea. Just don't support users running
-  git commands that affect the repository in this mode.
+  git commands that affect the repository in this mode. Probably.
 * However, `git status` and similar also will show deleted and new files,
   which will be helpful for the assistant to use when starting up.
 * Cache the mtime, size etc of files, and use this to detect when they've been
@@ -62,6 +63,8 @@ is converted to a real file when it becomes present.
   mapping needs to be updated.
 * May need a reverse mapping, from files in the tree to keys? TBD
   (Currently, getting by looking up symlinks using `git cat-file`)
+  (Needed to make things like `git annex drop` that want to map from the
+  file back to the key work.)
 * The existing watch code detects when a file gets closed, and in this
   mode, it could be a new file, or a modified file, or an unchanged file.
   For a modified file, can compare mtime, size, etc, to see if it needs
@@ -74,6 +77,10 @@ is converted to a real file when it becomes present.
   to files in this remote would not be noticed and committed, unless
   a git-annex command were added to do so.
   Getting it basically working as a remote would be a good 1st step.
+* It could also be used without the assistant as a repository that
+  the user uses directly. Would need some git-annex commands
+  to merge changes into the repo, update caches, and commit changes.
+  This could all be done by "git annex sync".
 
 ## TODO
 
diff --git a/doc/direct_mode.mdwn b/doc/direct_mode.mdwn
new file mode 100644
index 000000000..df5d64fa2
--- /dev/null
+++ b/doc/direct_mode.mdwn
@@ -0,0 +1,75 @@
+Normally, git-annex repositories consist of symlinks that are checked into
+git, and in turn point at the content of large files that is stored in
+`.git/annex/objects/`. Direct mode is an experimental mode that gets rid of
+the symlinks.
+
+The advantage of direct mode is that you can access files directly,
+including modifying them. The disadvantage is that most regular git
+commands cannot safely be used, and only a subset of git-annex commands
+can be used.
+
+## enabling (and disabling) direct mode
+
+Any repository can be converted to use direct mode at any time, and if you
+decide not to use it, you can convert back to indirect mode just as easily.
+Also, you can have one clone of a repository using direct mode, and another
+using indirect mode; direct mode interoperates.
+
+To start using direct mode:
+
+	git annex direct
+
+To stop using direct mode:
+
+	git annex indirect
+
+With direct mode, you're operating without large swathes of git-annex's
+carefully constructed safety net. So you're strongly encouraged to tell
+git-annex that your direct mode repository cannot be trusted to retain
+the content of a file (because any file can be deleted or modified at
+any time). To do so:
+
+	git annex untrust .
+
+## use a direct mode repository
+
+The main command that's used in direct mode repositories is
+`git annex sync`. This automatically adds new files, commits all
+changed files to git, pushes them out, pulls down any changes, etc.
+
+You can also run `git annex get` to transfer the content of files into your
+direct mode repository. Or if the direct mode repository is a remote of
+some other, regular git-annex repository, you can use commands like `git
+annex copy` and `git annex move` to transfer the contents of files to the
+direct mode repository.
+
+You can use `git commit --staged`. (But not `git commit -a` .. It'll commit
+whole large files into git!)
+
+You can use `git log` and other git query commands.
+
+## what doesn't work in direct mode
+
+Don't use `git annex add` -- it thinks all direct mode files are unlocked,
+and locks them.
+
+In general git-annex commands will only work in direct mode repositories on
+files whose content is not present. That's because such files are still 
+represented as symlinks, which git-annex commands know how to operate on.
+So, `git annex get` works, but `git annex drop` and `git annex move` don't,
+and things like `git annex fsck` and `git annex status` show incomplete
+information.
+
+It's technically possible to make all git-annex commands work in direct
+mode repositories, so this might change. Check back to this page to see
+current status about what works and what doesn't.
+
+As for git commands, you can probably use some git working tree
+manipulation commands, like `git checkout` and `git revert` in useful
+ways... But beware, these commands can replace files that are present in
+your repository with broken symlinks. If that file was the only copy you
+had of something, it'll be lost. 
+
+This is one reason it's wise to make git-annex untrust your direct mode
+repositories. Still, you can lose data using these sort of git commands, so
+use extreme caution. 
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 5a69fe496..4b4109820 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -263,6 +263,21 @@ subdirectories).
   settings, and when it exits, stores any changes made back to the git-annex
   branch.
 
+* direct
+
+  Switches a repository to use direct mode, where rather than symlinks to
+  files, the files are directly present in the repository. Note that many git
+  and git-annex commands will not work in direct mode; you're mostly
+  limited to using "git annex sync" and "git annex get".
+
+  As part of the switch to direct mode, any changed files will be committed.
+
+* indirect
+
+  Switches a repository back from direct mode to the default, indirect mode.
+  
+  As part of the switch from direct mode, any changed files will be committed.
+
 # REPOSITORY MAINTENANCE COMMANDS
 
 * fsck [path ...]
@@ -776,6 +791,12 @@ Here are all the supported configuration settings.
   to close it. On Mac OSX, this defaults to 1 second, to work around
   a bad interaction with software there.
 
+* `annex.direct`
+
+  Set to true to enable an (experimental) mode where files in the repository
+  are accessed directly, rather than through symlinks. Note that many git
+  and git-annex commands will not work with such a repository.
+
 * `remote.<name>.annex-cost`
 
   When determining which repository to
diff --git a/doc/index.mdwn b/doc/index.mdwn
index 85d93250f..2874a8552 100644
--- a/doc/index.mdwn
+++ b/doc/index.mdwn
@@ -49,6 +49,7 @@ files with git.
 * [[sync]]
 * [[encryption]]
 * [[bare_repositories]]
+* [[direct_mode]]
 * [[internals]]
 * [[scalability]]
 * [[design]]