mirrors/git-annex
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

starting a page about direct mode

Browse source
This commit is contained in:
Joey Hess 2012-12-12 15:36:00 -04:00
parent b0c5cbfde2
commit bfb446604a
1 changed files with 62 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
doc/direct_mode.mdwn Normal file
View file

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