129 lines
4.9 KiB
Markdown
129 lines
4.9 KiB
Markdown
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]]
|
|
|
|
## deprecated
|
|
|
|
Direct mode is deprecated! Instead, git-annex v7 repositories can simply
|
|
have files that are [[unlocked|tips/unlocked files]] and thus can be directly accessed and
|
|
modified. See [[upgrades]] for details about the transition to v7
|
|
repositories.
|
|
|
|
## 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`
|