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

to revert the last change to `file`. Note that you can use the `--depth`
flag to revert earlier versions of the 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`