The git-annex Windows port is beta, but rapidly becoming polished and usable!


  • There can be problems when the git-annex repository is in a deep or long path. Ie, C:\loooooooooooooooooongdir\. Details here

    Workaround: Put your git-annex repo in C:\annex or some similar short path if possible.

    Workaround: Enable long paths in the registry. See

    ghc 8.61 fixes this!

  • Local pairing seems to fail, after acking on Linux box, it stalls. (Also, of course, the Windows box is unlikely to have a ssh server, so only pairing with a !Windows box will work.)

  • gcrypt is not ported to windows (and as a shell script, may need to be rewritten)

  • Deleting a git repository from inside the webapp fails "RemoveDirectory permision denied ... file is being used by another process"

  • Tor remotes are not supported yet. Should not be very hard to get it working.

  • Due to bundling rsync.exe, the windows installer needs to be installed with git for windows 32 bit, not 64 bit. It would be possible to switch to a 64 bit rsync.exe build, but then 32 bit git for windows would not work. Better, perhaps, to drop rsync.exe from the bundle; it's only needed when talking to older versions of git-annex-shell, and of course for rsync special remotes, but if the users wants to use the latter, they can install rsync themselves.

    Postponed until old versions of git-annex-shell are less common..

potential encoding problems

?Unicode file names ignored on Windows is fixed, but some potential problems remain, since the FileSystemEncoding that git-annex relies on seems unreliable/broken on Windows.

  • When git-annex displays a filename that it's acting on, there can be mojibake on Windows. For example, "háčky.txt" displays the accented characters as instead the pairs of bytes making up the utf-8. Tried doing various things to the stdout handle to avoid this, but only ended up with encoding crashes, or worse mojibake than this.

  • md5FilePath still uses the filesystem encoding, and so may produce the wrong value on Windows. This would impact keys that contain problem characters (probably coming from the filename extension), and might cause interoperability problems when git-annex generates the hash directories of a remote, for example a rsync remote.

  • encodeW8 is used in Git.UnionMerge, and while I fixed the other calls to encodeW8, which all involved ByteStrings reading from git and so can just treat it as utf-8 on Windows (via decodeBS), in the union merge case, the ByteString has no defined encoding. It may have been written on Unix and contain keys with invalid unicode in them. On windows, the union merge code should probably check if it's valid utf-8, and if not, abort the merge.

  • If interoperating with a git-annex repository from a unix system, it's possible for a key to contain some invalid utf-8, which means its filename cannot even be represented on Windows, so who knows what will happen in that case -- probably it will fail in some way when adding the object file to the Windows repo.

  • If data from the git repo does not have a unicode encoding, it will be mangled in various places on Windows, which can lead to undefined behavior.

minor problems

  • webapp lets user choose to encrypt repo, and generate gpg key, before checking that gcrypt is not installed
  • Ssh connection caching does not work on Windows, so git annex get has to connect twice to the remote system over ssh per file, which is much slower than on systems supporting connection caching.
  • glacier-cli is not easily available (probably)

stuff needing testing

  • test that adding a repo on a removable drive works; that git is synced to it and files can be transferred to it and back
  • Does stopping in progress transfers work in the webapp?

do we need this port anymore?


If windows has transparent support for running linux executables, and those executables can access files in "." which are on the windows system, then you could just use this to run linux git-annex on windows. No port needed.

That would be great!

Seems like this would need Windows 10.

The latest builds of Windows 10 (build 15063) can run git-annex in the Windows Subsystem for Linux. After following the instructions at, run: sudo apt-get install git-annex

git-annex in WSL passes its full test suite, and it avoids all the problems discussed in sections above.

git-annex can access Windows files in eg /mnt/c, so a git-annex repository can be stored there. However, if the git-annex repository uses indirect mode, the symlinks used by git-annex won't be usable by Windows programs. Use either direct mode, or v6 mode to avoid the symlink problem.

Also, see this important caveat:

March 2017: WSL is currently rather annoying to enable. If it became easy enough to enable, note that "bash -c git-annex" works from a windows command prompt, and would probably work in a .bat file as well, so git-annex from the WSL could be transparently used on the windows side.

The webapp does not currently work. It doesn't know how to open a web browser from the linux side. There are also what look like some emulation problems around the daemonization code. git annex assistant --foreground does run, but while it notices when new files are added, it does not notice when existing files get modified. Probably an inotify emulation bug. --Joey

Update May 2018: With the latest MS Edge VirtualBox image, enabling WSL was much easier than before, just a matter of checking a single box and a reboot. No need to enable developer mode first. (Don't know if this will apply to commercial Windows 10 or only this VM image.)

Then bash was available in the menu, but it said no distro installed, and gave an url to a "Store" where Ubuntu, Debian, etc could be installed.

git-annex test had a failure this time, something to do with disk IO error and sqlite.

The assistant can run as a daemon now. It still doesn't notice some changes. Eg with "rm foo; echo new > foo", it got an inotify event for the removal, but missed the new creation.

Running git annex assistant when the assistant is running complains of a stale pid file, with the wrong pid number, but it doesn't start a second one.

webapp still can't open a web browser, but there's a way to do it from within WSL that it should be possible for it to use: powershell.exe Start ("powershell.exe" is in PATH)


The sqlite problem may be fixed in git-annex 7. I fixed some similar, less frequent crashes on Linux. Need to test on windows. --Joey