Guide

Set up Git sync

Keep the texts on your Draftling backed up and in sync with a private Git repository.

How it works

Draftling has a built-in Git client. Press Ctrl+W to connect to Wi-Fi, then Ctrl+G, and Draftling commits your edits, pulls in anything new from the server, merges the two, and pushes the result back, using the same standard HTTPS protocol that desktop git uses. A full commit history is kept in .git/ on the SD card, so you can also plug the card into a computer and work with it there.

This works with any standard Git host. Below are step-by-step instructions for the three most common ones. You only need to do this once per device.

No Wi-Fi at hand? You can also sync over a USB cable from a web browser on your computer.

Sync over USB with Draftbridge

Draftbridge synchronizes your Draftling with a GitHub or Codeberg repository through a USB cable, from a web browser, without Wi-Fi. You log in with your GitHub or Codeberg account in the browser, so there is no access token or git.cfg to set up by hand.

  1. Connect the Draftling to your computer with a USB cable. Use a desktop version of Chrome, Edge or Opera; Firefox and Safari do not support the Web Serial connection it needs.
  2. On the Draftling, press F1, select Sync via browser... (letter B) and choose Start. Draftling saves and closes your open documents and waits for the computer.
  3. On the computer, open bridge.draftling.art, log in with GitHub or Codeberg, choose the repository for your texts (or create a new one), and follow the instructions there to connect to the device and synchronize. The device shows the progress of each transfer.
  4. When it is done, select Finished on the Draftling (Enter or Esc).

The browser does the same steps as Draftling's own Wi-Fi sync, on the same Git repository on the SD card, so you can mix the two freely. Draftbridge points the device's git.cfg at the repository you chose; to sync over Wi-Fi as well, add an access token to it as described below.

Needs Draftling 1.0.17 or newer, on a board whose USB port is the ESP32-S3's built-in USB: the boards that offer "SD card via USB" in the F1 menu. The Seeed reTerminal E1001 and Sticky and the Elecrow CrowPanel 5.79" do not support it. The repository may contain only .md, .txt and .fountain files. Details: docs/sync-via-browser.md.

Wi-Fi sync: before you start

  1. Create an empty private repository on your Git host (no README, no .gitignore, no licence; a completely empty repository is simplest). Note its branch name; new repositories usually default to main.
  2. Make sure your Draftling can reach the Internet: use the Wi-Fi connection dialog in the F1 menu, or put a wifi.cfg file on the SD card root with your network name on the first line and the password on the second line. 
    MyHomeWiFi
sup3r-secret

Everything below ends with a small text file called git.cfg on the SD card root. Create it with any text editor. Keep it private: it contains an access token.

GitHub

  1. Open Settings → Developer settings → Personal access tokens → Fine-grained tokens and click Generate new token.
  2. Give it a name (e.g. draftling) and an expiry date.
  3. Under Repository access choose Only select repositories and pick your repository.
  4. Under Permissions → Repository permissions set Contents to Read and write. (This also switches Metadata to read-only automatically, which is fine.)
  5. Click Generate token and copy the value. It starts with github_pat_ and is shown only once.

git.cfg:

repo_url=https://github.com/YOUR-USER/YOUR-REPO
branch=main
token=github_pat_xxxxxxxxxxxxxxxxxxxx
author_name=Jane Doe
author_email=jane@example.com

GitLab

  1. Open your project and go to Settings → Access tokens.
  2. Click Add new token. Give it a name and an expiry date.
  3. Set the Role to Developer (or higher).
  4. Tick the read_repository and write_repository scopes.
  5. Click Create project access token and copy the value. It starts with glpat- and is shown only once. Note the token's name too; you need it as the username.

git.cfg:

repo_url=https://gitlab.com/YOUR-USER/YOUR-REPO
branch=main
username=draftling-token-name
token=glpat-xxxxxxxxxxxxxxxxxxxx
author_name=Jane Doe
author_email=jane@example.com

If you use a personal access token (User Settings → Access Tokens) instead of a project token, set username to your GitLab account username.

Codeberg

  1. Open Settings → Applications.
  2. Under Manage Access Tokens enter a token name (e.g. draftling).
  3. Expand Select permissions and set repository to Read and Write.
  4. Click Generate Token and copy the value. It is shown only once.

git.cfg:

repo_url=https://codeberg.org/YOUR-USER/YOUR-REPO
branch=main
username=YOUR-CODEBERG-USERNAME
token=xxxxxxxxxxxxxxxxxxxx
author_name=Jane Doe
author_email=jane@example.com

The same steps work for any Gitea or Forgejo host, not just Codeberg.

All the git.cfg settings

KeyRequiredMeaning
repo_urlyesRepository URL. A trailing .git is optional.
tokenyesThe access token you created above (used as the HTTPS password).
branchnoBranch to sync. Default main.
usernamenoHTTPS username. Default x-access-token (works for GitHub). GitLab and Codeberg need a real value (see above).
pathnoSync into this sub-directory of the repository instead of its root, e.g. notes/.
author_name
author_email		noIdentity stamped on the commits Draftling makes.

First sync

  1. Put git.cfg on the SD card root and insert the card.
  2. Power on Draftling and connect Wi-Fi: press Ctrl+W, or use the F1 menu.
  3. Press Ctrl+G to sync.

On the very first sync Draftling downloads the repository's history (nothing, for an empty repository), commits your current files, and pushes them up. After that, every Ctrl+G is a quick two-way merge.

If both sides changed the same lines of a file, Draftling writes both versions into the file with <<<<<<< / ======= / >>>>>>> markers and still commits, so nothing is ever lost. Edit the file to resolve it and sync again.

Full details of the protocol, the on-card layout and the merge behaviour are in docs/git-sync.md.

Troubleshooting