git-annex-turtle provides Apple Finder integration for git-annex on macOS, including custom badge icons (badges), contextual menus (control-clicks) and a Menubar icon (aka menubar extra). git-annex-turtle is a native Mac app written in Swift 4 with XCode 9.2 and requires macOS 10.12 or later.
git-annex-turtle is free, open-source and licensed under The MIT License. git-annex-turtle includes software and creative works/assets that are licensed under other open source licenses, see OTHER_LICENSES.txt for more information.
Sign-up for updates to receive an email about new version releases and infrequent announcements.
Download git-annex for macOS and install to your
/Applications folder. Follow the git-annex walkthrough if you have never used git-annex before.
Download git-annex-turtle stable beta release. Unzip and drag the application to your
/Applications folder. Requires: macOS 10.12 or later. Or if you need some bleeding edge feature try an unstable release.
Click the git-annex-turtle Menubar icon, then click
Preferences…, then click
+ to add a new git-annex repository to watch.
git-annex-turtle will then perform an initial
full scan of the repository you added. The full scan is required so that we may cache status information for folders, since only file-level status is stored by git and git-annex.
View your git-annex repository in Apple Finder to see updated badge icons. Right click (control-click) on a file or folder to see git-annex specific context menus. Badge icons will appear progressively as the full scan completes.
- badges: git-annex-turtle adds a badge icon (badges) for every file and folder in monitored git-annex repositories indicating present/absent status, number of copies and whether or not copies are lacking.
- contextual menus: git-annex-turtle adds contextual menus (control-clicks) to all files and folders (in monitored repos) allowing quick access to git-annex get/drop/add and more.
- menubar icon: git-annex-turtle adds a Menubar icon (aka menubar extra) showing animated activity status, monitored folder status and a preferences menu.
For files badges signify if they are present or absent, their number of copies and whether or not they have the desired number of git-annex copies (
numcopies). Present or absent status is signified by a filled (solid) in vs not-filled (empty) square. Number of copies is signified by digits ranging from 0 to 4 or a star for files with 5 or more copies. If a file has at least the amount of copies specified in your
numcopies setting (or in a
.gitattributes override) the icon is colored green, otherwise red.
For folders badges signify status of the files contained within. They signify if all the files are present, some are present or all are absent. If all files are present icon is a solid square, if all files are absent icon is an empty square, otherwise if some files are present icon is a partially filed square. The icon's digit signifies the number of copies of the file with the least copies contained within. If every file contained within the folder has at least the desired number of copies the icon is colored green, otherwise red.
macOS 10.12 or later
git-annex-turtle relies on the Apple Finder Sync API, which is only available on OS-X 10.10 (Yosemite) and later and all versions of macOS. The Liferay Nativity library could potentially be used to enable git-annex-turtle to run on older Mac OSs. I am also using features of CoreData which are only available on macOS 10.12 and later.
git-annex-turtle is released for the the Mac only; it is written in Swift with XCode so is probably not easily portable to Linux and Windows. You may, of course, adapt and use this app's user experience, design, workflow and icon sets when porting to other OSs. See git-annex related software for options already built for other OSs.
The Apple Finder Sync Extension only allows one extension to register itself per folder, so other apps might be conflicting with git-annex-turtle. For example, Dropbox, registers its Finder Sync extension on your entire home folder (Users/yourname), regardless of where your actual Dropbox folder is located. Dropbox does this, apparently, so they can have “move to Dropbox” context menus on every single file. Launch
System Preferences > Extensions > Finder to see what apps have Finder Sync extensions registered. If you want to continue using Dropbox, partially, you can disable
Finder Integration in their Preferences menu, cloud syncing then should still continue to operate.
App Group location for sqlite database. You may safely delete this folder if the app and all extension processes are not running. All full scans will then restart on the next launch of git-annex-turtle.
Stores config settings for git-annex-turtle, that are editable through the menubar icon or by editing the file directly. Uses git config style syntax. You may safely update this file manually and the app will detect your changes, but note that adding and removing repos via the GUI will clobber any comments or unknown lines you have added manually to this file.
git-annex-turtle takes inspiration in function and name from TortoiseCVS and the many other tools which have provided OS-level filesystem icons for source revision control software.
- Install XCode 9.2
- Install XCode SDK macOS 10.12 for XCode 9.2
- Open src/git-annex-turtle.xcodeproj in XCode
- Create a new scheme called git-annex-turtle with build targets
- Run the
Build a Release
Clone git-annex-turtle repo, then run build-release script
cd git-annex-turtle ./.build-local-release.sh
Release will now be at