Syncing your project to a git remote

Every save in the editor is already a commit in the project's own git repository on the server. Sync mirrors that history to a repository you control — typically on GitHub — after each save, giving you an off-site backup you can clone, read, and keep forever.

Sync is part of Pro, and only a project's owners can set it up. Cloning straight from TeXType (below) works on every plan.

Pushing is automatic; pulling is a button. Every save pushes to your repository. Commits made directly on GitHub do not stream in live — press Pull in the sync dialog to bring them in. A remote that is simply ahead applies cleanly; a true divergence offers a merge (conflicts become markers in the text, resolved together in the editor) or adopting the remote's history outright — which is also how you initialize a fresh project from an existing repository.

1 · Create a repository to sync into

On GitHub: New repository, private, any name.
Create it empty — do not tick "Add a README". An empty repository accepts the first push cleanly; sync never creates repositories for you.

If you must sync into a repository that already has history, don't use its existing branch — in step 3, set the branch to an unused name such as textype. The Check target button in the sync dialog will tell you whether your choice is safe before anything is pushed.

2 · Create a fine-grained personal access token

A fine-grained token can be limited to exactly one repository with exactly one permission, so a leak of this credential exposes only this backup — not your account.

On GitHub, open Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
Resource owner: you (or the organization that owns the repository).
Expiration: your choice; a year is reasonable. No need to note the date: the project's sync indicator turns amber two weeks before the token lapses (the dialog shows the exact day), and pasting a fresh token is the whole fix.
Repository access: Only select repositories → pick the repository from step 1.
Permissions → Repository permissions → Contents: Read and write. (Metadata: read-only is added automatically.) Nothing else is needed.
Generate, and copy the token — GitHub shows it only once.

Organization-owned repository? The organization must allow fine-grained tokens (some require an approval step after you create one). If yours doesn't, a classic token with the repo scope works everywhere but grants access to every repository you can reach — scope it mentally as "my whole account" and store it nowhere else. For SAML/SSO organizations, remember to click Authorize for the org after creating a classic token.

3 · Connect it in the sync dialog

Paste the token into Access token and click Save token and browse. Pick your repository from the list — the URL and branch fill themselves in. (Or paste the repository's https://… URL by hand.)
Leave Username blank — with a personal access token, GitHub ignores it. (GitLab wants your username there; see GitLab below.)
Branch: main for an empty repository; an unused name like textype otherwise.
Click Check target and read what it says.
Leave Push automatically after every save on — it is the default — then Save, then Push now.
Refresh the repository on GitHub — your project's full history is there.

From now on, edits push themselves: about ten seconds after a save, one push carries everything since the last. The dialog's status line shows the last pushed commit. Failures appear there too, with an explanation. Most are retried automatically; a rejected token or a missing repository waits until you change the sync settings.

Where the token lives

The token is encrypted on the server the moment it is saved and is never sent back to any browser — the dialog can only replace it, not reveal it. Even so, scope tokens minimally: one repository, contents-only, with an expiry.

When it breaks later

"The remote rejected the credentials" — the token expired or was revoked. Create a new one (step 2), paste it into the token field, and Save; every other field can stay as it is.
"The remote has commits this project does not" — someone committed directly to the synced branch on GitHub. See fixing a branch that was pushed to by accident, just below.
Host unreachable — nothing to do; pushes retry with backoff and catch up on their own.

Fixing a branch that was pushed to by accident

Pushes stop with "the remote has commits this project does not" when something landed on the synced branch outside the editor — an edit made directly on GitHub, or a push from a clone. The Pull button in the sync dialog resolves this in place now (merge, or adopt the remote); the manual routes below remain for when you want them. Two ways, safest first.

Option 1 — sync to a fresh branch. Zero risk, ten seconds:

In the sync dialog, change Branch to an unused name (backup-2, say).
Save, then Push now. The project's full history lands on the new branch.
The old branch stays on GitHub untouched. If the stray commits contain anything worth keeping, read them there at your leisure and paste what matters back into the editor.

Option 2 — keep the branch name by resetting it. This discards the stray commits from GitHub, so salvage first:

If anything in the stray commits matters, bring it back through the editor: view the commit on GitHub and paste the changes into the project. That is how external work re-enters — the editor's copy is the one that counts.
On GitHub, delete the synced branch: repository → Branches → 🗑. If GitHub refuses because it is the repository's default branch, first switch the default to any other branch (Settings → General → Default branch — create one from the GitHub UI if there is nothing else), then delete.
Back in the editor: Push now. The branch is recreated with the project's full history, and automatic pushes resume.

Prevention: on GitHub, a branch protection rule on the synced branch that restricts who may push (just you — the sync token acts as you) means collaborators with repository access cannot land on it by accident in the first place.

GitLab

The same three steps, with GitLab's names for things. Works for gitlab.com and for a self-hosted GitLab whose address contains "gitlab" (such as gitlab.example.edu): the sync dialog recognizes GitLab from the URL. For a GitLab at another address, paste the clone URL and use Check target; browsing is not available there.

Create an empty project on GitLab: New project → Create blank project, private, and untick Initialize repository with a README.
Create a personal access token: your avatar → Preferences → Access tokens → Add new token. Scopes: read_repository and write_repository. Nothing else. Set an expiry; the sync indicator warns two weeks before it lapses.
In the sync dialog: first paste the new project's HTTPS clone URL (on GitLab, Code → Clone with HTTPS) into Remote URL. A blank Remote URL means GitHub, so the dialog would send your GitLab token there. Username is your GitLab username (the one in your profile URL, not your email), and the token goes in Access token. Then Save; Save token and browse lists your GitLab projects if you want to pick another.

Project access tokens (created inside one project's settings rather than your account's) work too, with the same two scopes; then the username is the token's name, and the browser lists only that one project — by design, it is all the token can see. If the browser shows no projects or reports the token rejected, this is the first thing to check.

A push that fails with "HTTP 502" even though the target check succeeded is gitlab.com refusing a push sent in chunks. The editor sends pushes whole to avoid it, and retries automatically; if it persists, it is gitlab.com having a bad minute, not your configuration.

Cloning straight from TeXType

You do not need GitHub to have the project on your own machine. TeXType is itself a git remote, on every plan:

On your account page, under Access tokens, make a token for the project. Copy it; it is shown once.
Copy the clone command shown when you make the token (if you own the project, it is also under Clone with git in its Sync dialog), and run it:
```
git clone https://textype.io/git/<project-id>
```
When git asks, give any username and the token as the password. Your system's credential helper remembers it, so git pull later just works.

The clone has the files and their whole history, including what was typed a moment ago: the project saves before git reads it. Comments and suggestions are not files and are not in the clone; they stay in TeXType.

Clone and fetch only, for now. git push to TeXType is refused with a message saying so; change the project in the editor, or keep using sync to GitHub or GitLab. A token stops working when it expires, when you revoke it, when you sign out of every device, or when you leave the project.

Other hosts

The repository browser knows GitHub and GitLab, but sync itself speaks to anything that accepts an authenticated https:// push:

Gitea / Forgejo / others: any access token that can push over HTTPS works; username requirements vary by host. Paste the clone URL and use Check target.
Only https:// addresses are supported. SSH addresses (ssh://… or git@host:…) are refused: TeXType cannot sync over SSH. Use the repository's https:// address with an access token instead.

Other guides

Using AI tools with TeXType: connecting Claude, ChatGPT or Codex to your projects, and reviewing what they suggest. AI tools never push to git; the sync and clone described here stay yours.