Currently shared decks are edited locally, then uploaded to Anki’s servers where they sit as the final version until the author overwrites it. As a user of shared decks, I often find errors that I’d like to correct in the original version, or expand on the content of a partial deck, but I don’t see a way to share these improvements without duplicating the deck in the directory. To handle collaborative deck authorship, I’d like to suggest the option for decks to be managed via GitHub. (I know this is a large change, but I’d like to get the conversation started if there is interest.)
With GitHub as the method for submitting improvements to the original deck, the original author could either accept the PR to the deck, or the contributor could publish a forked version of the deck, but the Anki directory would be able to group forks with the original deck so end users can see what related versions are available in one place.
Has there been any discussion of moving the deck server to use a git-based model so that decks can be versioned and incrementally improved like software? To clarify, I’m not suggesting that users’ local decks be managed via git, this change would only affect how shared decks are managed/modified on the server and displayed to the end user for download.
1 Like
As a bit of a personal project, I have a deck that I’m generating from a yml file that I’m editing and that is also in git. While I import cards into Anki manually, this can be easily automated. I suppose you could even figure out automatic updating of the shared deck. There’s no API but simulating web stuff is easy these days. Put that all into GitHub actions and you are set!
This of course assumes that all of collaborators know git. Kind of ruins the whole idea.
Anyway, I’ve heard about a few related projects. AnkiHub is an upcoming paid service that promises to be feature rich. AnkiSync is also something new… it kind of works but I have no idea who made it and what is planned. Neither of these seem to use git under the hood, unlike ki. I’m really not sure how to use ki. The documentation is there, but… Oh well.
3 Likes
Why specifically through github? Since there are git web interfaces for local git repositories ready to be installed on any webserver, since Anki already stores on its server all the addons, and since Anki already has a webserver, it would make sense to me that these git repos would be available directly on anki webpage.
Also, I’m not too sure about how you can store decks in a git repository without forcing the author to do so. If the author never catches up with the updates on the server-side (ie. new commit that he didn’t make), then each time they upload their new version they would simply have to erase everything else, wouldn’t they?
1 Like
The general idea is that if a deck author wanted to make their deck collaborative, any changes to that deck could be managed through PRs to the GitHub repo. When a user wanted to download that deck from the Anki web app, it would get the latest version of that deck from the GitHub repo.
This doesn’t support syncing/updating users’ copies of that deck after they’ve downloaded it, but it would allow GitHub to serve as the source of truth for the deck and for multiple people to contribute updates to that shared deck in a git-managed way. If the author wanted to update the shared deck, then I envision them exporting their personal deck in the format stored in git, then using that export to make changes in their local version of the repo which generates a local git diff, then push those changes in a commit to GitHub. Only new downloads of the deck would receive those changes.
Obviously, this isn’t an ideal system, but Anki wasn’t really designed for this. So this would be an incremental improvement on modification and distribution of shared decks, but doesn’t change the pattern of a one-time download.
I guess you’re right that it doesn’t have to be GitHub, but they do provide a lot of other tools for discussing changes, forking repos, and generally serving as the hub for open-source data.
Hey! In case you would like to check it out, the following command-line tool does exactly what you’re asking: GitHub - langfield/ki: version control for Anki collections
You can look at an example collaborative deck here: GitHub - langfield/A2_Wortliste_Goethe: A2 Wortliste Goethe (vocab, sentences, audio, translation)
And if you install ki and add this deck as a git submodule in your collection, you can make changes inside Anki, pull them into the git repository representation of your collection, commit them, and then make a PR to the repository!
I am pretty desperate for user feedback for this thing, so please try it out if you have the time! I would be happy to walk you through basic usage or answer any questions you have.
2 Likes
Your project seems nice and I’ll definitively check it out, but one thing I think would be very helpful right away would be a list of features. I already have a vc setup for editing Anki decks (even though I don’t currently use it because I don’t have much to learn rn), so it would be helpful if I could quickly compare ki with what I currently have. To be more specific, it seems to me that ki does multiple things, in the sense that its features span across what multiple components do for me, but I’m not completely sure because there isn’t an exhaustive feature list. Having that list would allow me to understand where, in my workflow, I would have to replace some components with ki to make it all work nicely.
@BlackBeans your wish is my command! I have added an exhaustive feature list to the README.
Copying it here for convenience:
Features
Ki provides three high-level features:
-
Cloning your collection of Anki cards into a folder (called a repository)
of human-readable markdown files.
-
Pulling changes you make in Anki into your repository.
-
Pushing changes you make to the markdown files in your repository back to
Anki.
It also supports:
-
Collaborative decks on GitHub via git submodules, which means you can
download shared decks, upload your own, contribute changes to others’ decks,
and review/merge others’ contributions to your own decks.
-
Full version history of your decks, with the ability to roll-back to
any previous commit of your
collection (these are made any time you run a ki command).
-
Automatic backups of your collection before every write to the
Anki database file
(you can find these in your repository in the .ki/backups directory).
- Support for
Basic, Basic (and reversed), Cloze, Cloze-Overlapper, and
any arbitrary notetypes you make.
- Full version history of edits to all your notetypes.
- Full version history of all your media files.
- Private fields for collaborative decks (so you can make your own notes and
edits, and still get updates from deck maintainers without losing any data).
- Auto-indentation and tidying of HTML in note fields and notetype templates.
- Human-readable filenames (the filename is generated from a note’s sort field
content).
- Meaningful card file locations. If you move a card file to a different deck
folder, it will move that card to that deck.
- Meaningful card file deletions. If you delete a card file in your repository,
the card is deleted from your collection (but only if you commit the
deletion, and because everything is version-controlled, you can always get it
back).
- Manually adding new notes. You can write a markdown file in the ki note
format and push the new note to Anki, or you can copy an existing note to
make a variant of it.
-
Granular merge conflict resolution. AnkiSync forces you to either
overwrite everything with the sever-side version, or your local version
when it doesn’t know how to automatically sync your decks. With Ki, you can
pick and choose which things you want from the server, and which things you
want to keep from your device.
- Collision-free reads and writes to the
collection.anki2 database file via
SQLite3 lock acquisition (no errors from editing the collection at the same
time as the Anki desktop client).
- Atomic database writes (we edit a copy of the collection in a temporary
directory, and then replace the existing collection in a single
shutil.copyfile() call.
- Changes are only pulled when the hash of the database has changed.
- Warnings for duplicate notes, unhealthy notes, etc.
- Cards for a single note split across multiple decks (these are represented
with symlinks).
- Potential interoperation with mobile apps. The note grammar is programming
language-agnostic, and so a parser could be written in e.g. Kotlin to import
decks from GitHub right on your phone, but this would take a nontrivial
amount of development effort.
- Unicode (
UTF-8), foreign language characters, and symbols in all fields.
- Properly-escaped
LaTeX and MathJaX.
2 Likes
Wow, impressive! I think it would make sense moving all the discussion about ki to their own thread.