diff options
author | Joey Hess <joeyh@joeyh.name> | 2015-11-10 12:55:41 -0400 |
---|---|---|
committer | Joey Hess <joeyh@joeyh.name> | 2015-11-10 12:55:41 -0400 |
commit | 071ad29c5e72226de2e0fb12beafc2b1c5f6ef0c (patch) | |
tree | eb2510862cf92e9d9c2ecd457cbf33667c679541 /doc/direct_mode.mdwn | |
parent | 3607ec7f549e67028115d3ccb3bd870ad1106f13 (diff) |
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.
Diffstat (limited to 'doc/direct_mode.mdwn')
-rw-r--r-- | doc/direct_mode.mdwn | 121 |
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` |