Revert deleton of direct mode page

This reverts commit 27622afad32235b4b3ad2a49facfe348249f9b89.

This may have been an accident, but if it happens again, MARCAO8 will be
banned.

1 files changed, 121 insertions, 0 deletions

diff --git a/doc/direct_mode.mdwn b/doc/direct_mode.mdwn
index 8b1378917..4c2cb2dd7 100644
--- a/doc/direct_mode.mdwn
+++ b/doc/direct_mode.mdwn
@@ -1 +1,122 @@
+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 gets rid of the symlinks.
 
+The advantage of direct mode is that you can access files directly,
+including modifying them. The disadvantage is that many regular git
+commands cannot be used in a direct mode repository, since they don't
+understand how to update its working tree.
+
+[[!toc]]
+
+## enabling (and disabling) direct mode
+
+Normally, git-annex repositories start off in indirect mode. With some
+exceptions:
+
+* Repositories created by the [[assistant]] use direct mode by default.
+* Repositories on FAT and other less than stellar filesystems
+  that don't support things like symlinks will be automatically put
+  into direct mode.
+* Windows always uses 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.
+
+To start using direct mode:
+
+	git annex direct
+
+To stop using direct mode:
+
+	git annex indirect
+
+## safety of using direct mode
+
+With direct mode, you're operating without large swathes of git-annex's
+carefully constructed safety net, which ensures that past versions of
+files are preserved and can be accessed. 
+With direct mode, any file can be edited directly, or deleted at any time,
+and there's no guarantee that the old version is backed up somewhere else.
+
+So if you care about preserving the history of files, you're strongly
+encouraged to tell git-annex that your direct mode repository cannot be
+trusted to retain the content of a file. To do so:
+
+	git annex untrust .
+
+On the other hand, if you only care about the current versions of files,
+and are using git-annex with direct mode to keep files synchronised between
+computers, and manage your files, this should not be a concern for you.
+
+## use a direct mode repository
+
+You can use most git-annex commands as usual in a direct mode repository.
+
+Direct mode also works well with the git-annex assistant.
+
+The most important command to use in a direct mode repository is `git annex
+sync`. This will commit any files you have run `git annex add` on, as well
+as files that were added earlier and have been modified. It will push 
+the changes to other repositories for `git annex sync` there to pick up,
+and will pull and merge any changes made on other repositories into the
+local repository.
+
+## what doesn't work in direct mode
+
+A very few git-annex commands don't work in direct mode, and will refuse
+to do anything. For example, `git annex unlock` doesn't make sense in
+direct mode.
+
+As for git commands, direct mode prevents using any git command that would
+modify or access the work tree. So you cannot `git commit` or `git pull`
+(use `git annex sync` for both instead), or run `git status` (use `git
+annex status` instead). These git commands will complain "fatal: This
+operation must be run in a work tree".
+
+The reason for this is that git doesn't understand how git-annex uses the
+work tree in direct mode. Where git expects the symlinks that get checked
+into git to be checked out in the work tree, direct mode instead replaces
+them with the actual content of files, as managed by git-annex.
+
+There are still lots of git commands you can use in direct mode. For
+example, you can run `git log` on files, run `git push`, `git fetch`,
+`git config`, `git remote add` etc.
+
+## proxing git commands in direct mode
+
+For those times when you really need to run a command like `git revert
+HEAD` in a direct mode repository, git-annex has the ability to proxy
+the command to work in direct mode.
+
+For example:
+
+	git annex proxy -- git revert HEAD
+
+	git annex proxy -- git checkout HEAD^^
+
+	git annex proxy -- git mv mydir newname
+
+This works by setting up a temporary work tree, letting the git
+command run on that work tree, and then updating the real work
+tree to reflect any changes staged or committed by the git command,
+with appropriate handling of the direct mode files.
+
+## undoing changes in direct mode
+
+There is also the `undo` command to do the equivalent of the above revert
+in a simpler way. Say you made a change in direct mode, the assistant
+dutifully committed it and you realise your mistake, you can try:
+
+    git annex undo file
+
+## forcing git to use the work tree in direct mode
+
+This is for experts only. You can lose data doing this, or check enormous
+files directly into your git repository, and it's your fault if you do!
+
+Ok, with the warnings out of the way, all you need to do to make any
+git command access the work tree in direct mode is pass it 
+`-c core.bare=false`