git-annex/ direct mode

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 was a hack to avoid the symlinks.

The advantage of direct mode was that you can access files directly, including modifying them. The disadvantage was that many regular git commands could not used in a direct mode repository, since they don't understand how to update its working tree.

Direct mode has been removed from git-annex as of version 7.20190826. The first time a new git-annex is run in a direct mode repository, it automatically converts it to a v7 repository with unlocked. See upgrades for details about the transition to v7 repositories.

comment 8

asbraithwaite: No, as far as I know it can not.

Comment by arand — Wed Oct 29 14:05:27 2025
comment 7

Would it be safe to add largefiles to gitignore in direct mode?

Can git-annex still track large files ignored by git?

Thanks. :-)

Comment by http://caust1c.myopenid.com/ — Wed Oct 29 14:05:27 2025
comment 6
`.git/annex/objects` does not typically contain any file contents in direct mode. The file contents are stored directly in the working tree.
Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
What happens to object database in direct mode?

What happens to the object database (`.git/annex/objects`) when going to direct mode? Are the objects deleted, moved to another location, kept?

If the objects are kept, does it means that the file on the repository in direct mode is duplicated in the object database? If so, would it be relevant to use `cp --reflink=auto` to populate the working directory to enable copy on write on filesystems that supports it?

Comment by mildred — Wed Oct 29 14:05:27 2025
comment 4

    git annex add $file
    git annex sync
    git annex copy $file --to otherrepo

Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
comment 3

So, if I edit a "content file" (change a music file's metadata, say), what's the workflow to record that fact and then synchronise it to other repositories?

I can't do a `git add`, so I don't understand what has to happen as a first step. (Thanks for your quick reply above, BTW.)

Comment by https://www.google.com/accounts/o8/id?id=AItOawl2Jj8q2upJL4ZQAc2lp7ugTxJiGtcICv8 — Wed Oct 29 14:05:27 2025
comment 20

Indirect mode is the recommended thing to use, except for situations where it doesn't work, then direct mode is used as a fallback.

v6 is getting fairly close to working better than direct mode at this point.

Comment by joey — Wed Oct 29 14:05:27 2025
comment 19
This page says direct mode is "deprecated"; but, v6 is not yet official ( https://git-annex.branchable.com/forum/default_repo_version_is_still_563/ )? So, for now, direct mode is the recommended thing to use?
Comment by Ilya_Shlyakhter — Wed Oct 29 14:05:27 2025
comment 1

This page mentioned a --depth option, but no, it was never implemented. I have updated this page.

If you need something simpler than the basic undo, you can use `git annex proxy` to run eg, a `git revert`.

(Deleted a forum thread that duplicated the previous comment.)

Comment by joey — Wed Oct 29 14:05:27 2025
--depth undo option
Well I just spent 4 hours building a OSX GUI around git annex undo --depth and it responds with "git-annex: unrecognized option '--depth'"... lol Please tell me that option exists somewhere other than the documentation... lol
Comment by mitzip — Wed Oct 29 14:05:27 2025
comment 16
i believe this is answered here. TLDR; basically NTFS + symlink works in Linux, but not in Windows/Cygwin, which git-annex seems to be using. YMMV.
Comment by https://id.koumbit.net/anarcat — Wed Oct 29 14:05:27 2025
Non-direct mode for Windows
Why Windows is restricted to direct mode? NTFS has symbolic links too. Is that fundamentally different from POSIX symlinks that it cannot be done?
Comment by https://www.google.com/accounts/o8/id?id=AItOawmjjrCHEIa4vpDIJoBuJsrF3y8wZQElVHw — Wed Oct 29 14:05:27 2025
comment 15
No, you can sync before you copy, get, or whatever. git-annex will replace the symlinks with the actual files when they arrive at the repository.
Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
Git annex copy needed before git annex sync

Thanks for these details @joeyh. But AFAIU, one needs to proceed to the git annex copy before doing the git annex sync, otherwise, symlinks (or files containing the symlink path on SMB) will be created, instead of the plain "direct" files that are expected.

I'm still not sure whether the git annex sync needs to be issued on either of the indirect or direct remotes first, or both, then in which sequence. I think a "walkthrough" script would help.

Comment by http://olivier.berger.myopenid.com/ — Wed Oct 29 14:05:27 2025
comment 14

I kinda wish people would post questions to the forum, and not clutter up this page..

Anyway, there have been past bugs in the direct mode code that caused some files to not be checked out in direct mode, but stay as symlinks pointing at the content. That can be fixed by running `git annex fsck`. But, I am not aware of any problem that can leave a git-annex symlink that is not checked into git at all. Perhaps you copied the symlink from another location?

Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
comment 13

@obergix asked:

> But then, how can a direct repo sync with changes made in other remotes, if there no pull/fetch available.

The answer is simple: By running `git annex sync`, which handles all that.

Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
Re: Fixing symlinks to the annex store in direct mode
What I said was just wrong. Instead of trying on tr.html, I tried with a copy of that file. But making the copy of that file had the wanted effect, transforming the symlink to the actual file. Probably the assistant monitoring file creation, and transforming indirect file to direct file. Or perhaps the `cp` command follows symlinks by default (I thought it didn't).
Comment by http://mildred.fr/ — Wed Oct 29 14:05:27 2025
Fixing symlinks to the annex store in direct mode

I have an issue with direct mode: I have tons of symlinks that points to the git-annex store, while in direct mode. After investigation, I found that these files don't seem to be part of the repository. I can check with:

    $ git -c core.bare=false status --porcelain tr.html
    ?? Documentation/Mozilla/developer.mozilla.org/tr.html

    $ ls -l tr.html
    lrwxrwxrwx 1 mildred mildred 205 10 juin  16:22 tr.html -> ../../../.git/annex/objects/gF/z1/SHA256E-s31895--c873982bd742ba8db6e026afee26b7ab2f75f54f587304d8c2d877db3900c0f6.html/SHA256E-s31895--c873982bd742ba8db6e026afee26b7ab2f75f54f587304d8c2d877db3900c0f6.html

The link is valid, and is probably pointing to a unused file in the annex store. How to add these files back?

If I was in indirect mode, I could simply use `git add tr.html` (and not `git annex add`). This would stage to the git staging area the symlink, and all would be well.

I found that in direct mode, the same was true. The command is:

    git -c core.bare=false add tr.html

The file is added to the repository, and the link is converted to the target file. The question now is why? There is no hook on the add command. Could it be the annex assistant? If that didn't worked, my question would have been: how to checkout a file in direct mode?

Comment by http://mildred.fr/ — Wed Oct 29 14:05:27 2025
comment 12

There should be no obstacles to using direct mode on one clone of a git repository, and indirect mode on another clone. The data stored in git for either mode is identical, and I do this myself for some repositories.

@valhalla, you probably need to run `git annex fsck`, and if that does not solve your problem, you need to file a bug report.

Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
Direct mode clone of an indirect repo

I too have issues with mixing direct and indirect mode repositories.

I have a regular, existing repository with ebooks, shared between various clones on proper :) filesystems; now I would need a copy of some of them on an ereader which only offers a FAT filesystem, so it has to be direct mode.

    mount $READER
    cd $reader
    git clone $REPO

I get a directory full of small files, the way git manages links on FAT.

    git annex init "ebook reader"

This detects the fact that it is working on a crippled filesystem, enables direct mode and disables ssh connection caching; up to now everything seems to be fine, but then

    git annex get $SOME_BOOK

seems to work, downloads the file somewhere, but when I try to open $SOME_BOOK it is still the fake link, and the file has been downloaded in its destination, as if the repo wasn't in direct mode.

I use version 4.20130723 on debian jessie

Comment by http://www.gl-como.it/author/valhalla/ — Wed Oct 29 14:05:27 2025
Comments on this page are closed.