starting a page about direct mode

1 files changed, 62 insertions, 0 deletions

diff --git a/doc/direct_mode.mdwn b/doc/direct_mode.mdwn
new file mode 100644
index 000000000..552725249
--- /dev/null
+++ b/doc/direct_mode.mdwn
@@ -0,0 +1,62 @@
+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.
+
+## make a direct mode repository
+
+To make a repository using direct mode, either make a fresh clone of an
+existing repository, or start a new repository. Then configure direct mode:
+`git config annex.direct true`
+
+You're strongly encouraged to tell git-annex that direct mode repositories
+cannot be trusted to retain the content of a file (because it can be
+deleted or modified at any time). To do so: `git annex untrust .`
+
+## use a direct mode repository
+
+You can use `git annex add` to add files to your direct mode repository.
+
+The main command that's supported in direct mode repositories is
+`git annex sync`. This automatically 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
+
+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. With direct mode, you're operating without large
+swathes of git-annex's carefully constructed safety net.