git-annex/ special remotes/ adb

This special remote stores files on an Android device.

The `adb` program is used to access the Android device, which allows connecting to it in various ways like a USB cable or wifi.

## example

To add a remote for the /sdcard/DCIM directory on the Android device, allowing to import and export photos:

    git annex initremote android type=adb androiddirectory=/sdcard/DCIM encryption=none exporttree=yes importtree=yes
    git annex export master --to android

## configuration

A number of parameters can be passed to `git annex initremote` to configure the adb remote.

- `androiddirectory` - Set to the location on the Android device where files for the special remote are stored.

- `androidserial` - Normally this is not needed, but if multiple Android devices are accessible, you'll be prompted to use it to specify which one to use.

- `exporttree` - Set to "yes" to make this special remote usable by git-annex-export. It will not be usable as a general-purpose special remote. Since this makes the exported files easily browsable on the Android device, you will almost always want to enable this.

- `importtree` - Set to "yes" to make this special remote usable by git-annex-import. When set in combination with exporttree, this lets files be imported from it, and changes exported back to it.

- `annexobjects` - When set to "yes" along with "exporttree=yes", this allows storing other objects in the remote along with the exported tree. They will be stored under .git/annex/objects/ in the remote.

- `oldandroid` - Set to "yes" if your Android device is too old to support `find -printf`. Enabling this will make importing slower. If you see an error like "bad arg '-printf'", you can enable this option, by running eg: `git-annex enableremote android oldandroid=yes`

- `ignorefinderror` - Set to "yes" to ignore errors when running "adb find" on the Android device. This can be useful eg, if some subdirectories are not readable, to let it import the other things that are readable.

- `encryption` - One of "none", "hybrid", "shared", or "pubkey". See encryption.

- `keyid` - Specifies the gpg key to use for encryption.

- `chunk` - Enables chunking when storing large files.

failing with `Operation not petmitted`

I also found the answer on my own.

The trick was hidden under my redaction. The filenames had special characters which are problematic under Android. Removing them solved the issue.

Comment by octvs — Tue Jul 22 18:11:47 2025
Disabling a special remote

Finally found the answer on my own:

    git config remote.phone.annex-sync false

Comment by dud225 — Tue Jul 22 18:11:47 2025
failing with `Operation not petmitted`

I recently faced with a fail

    ...
    export pixel podcasts/<redacted>.mp3
    adb: error: failed to copy '../../.git/annex/objects/17/vK/SHA256E-s57638506--06c92a06db07fa511271e5426c9447cb0fab551d7ba2b9c9d26d3c7e3f975b5c.mp3/SHA256E-s57638506--06c92a06db07fa511271e5426c9447cb0fab551d7ba2b9c9d26d3c7e3f975b5c.mp3' to '/storage/emulated/0/home/media/podcasts/not-related/<redacted>.mp3': remote couldn't create file: Operation not permitted
    ../../.git/annex/objects/17/vK/SHA256E-s57638506--06c92a06db07...1 file pushed, 0 skipped. 37.0 MB/s (57638506 bytes in 1.487s

      adb failed to store file
    failed
    (recording state in git...)
    export: 2 failed

Everything is done as usual on the phone, barring two all other files are succesfully sent. Any clues what might be the cause?

Comment by octvs — Tue Jul 22 18:11:47 2025
Disabling a special remote

Is there any way to enable a special remote on demand?

My configuration is comprised of local standard remotes (directories located on the same computer) and my phone as described in the Android tutorial [1]. I've noticed that git-annex automatically ignores the standard remotes that are missing (the aforementioned directories actually map to external drives that may or may not be connected), that's perfect, but for the phone special remote it seems to always try to connect to it, as a result the command "git annex sync" constantly outputs error messages:

    list phone error: device 'xxxx' not found

    git-annex: Unable to list contents of phone: adb find failed
    failed

[1] https://git-annex.branchable.com/tips/android_sync_with_adb/

Comment by dud225 — Tue Jul 22 18:11:47 2025
comment 4

It would probably be better to file a bug report about it than to discuss the problem here. I guess something you could include in the bug report is how many files are in the directory.

It may be that android's `find` command is either not breaking up the list of files that it passes to the -exec command at all, or is confused about how big an argument list it can build up. So this could also depend on your version of Android, so be sure to include that in the bug report.

Comment by joey — Tue Jul 22 18:11:47 2025
Import fails with

I am getting the following error on recent imports using the adb remote:

    list android find: exec stat: Argument list too long

    git-annex: Unable to list contents of android: adb find failed
    failed
    git-annex: import: 1 failed

I dont know if this is due to a recent update of git-annex or simply the growth of the files on my phone.

Cheers, Steffen

Comment by post — Tue Jul 22 18:11:47 2025
comment 2

@iakornfeld, like all special remotes, the git repository is not stored in the special remote, only the content of annexed files.

Using `git annex export` like in the example, the android device will contain files with the same names as those in your git-annex repository.

If you want to use a git-annex repository on the Android device, see Android instead of this. However, for pushing a tree of annexed files to Android device and updating it, this special remote can be a good fit.

Comment by joey — Tue Jul 22 18:11:47 2025
Git
Does this remotely access a normal repository, or does it store the files directly (with the metadata stored on the host)?
Comment by iakornfeld — Tue Jul 22 18:11:47 2025
Comments on this page are closed.