git-annex/doc/direct_mode.mdwn

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 most regular git
commands cannot safely be used, and only a subset of git-annex commands
can be used.

Repositories created by the [[assistant]] use direct mode by default.

## 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

You can use most git-annex commands as usual in a direct mode repository.
A few commands don't work in direct mode, and will refuse to do anything.

Direct mode also works well with the git-annex assistant.

You can use `git commit --staged`. But not `git commit -a` .. It'll
commit whole large files into git!

## what doesn't work in direct mode

`git annex status` show incomplete information. A few other commands,
like `git annex unlock` don't make sense in direct mode and will refuse to
run.

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.