Every TeXposit project is already a full git repository under the hood, with an attributed commit for every save. GitHub Sync connects that history to a real repository on GitHub, either as a one-way backup or as a two-way sync.

Connecting Your Account

Go to your Profile → Account tab and click Connect GitHub. This is a standard GitHub OAuth authorization, not a GitHub App install, so there's no organization admin approval step for your own repos. You can also trigger the same flow from a project's Settings, or from the Import from GitHub button on the projects dashboard, the first time you use either.

TeXposit connects to exactly one GitHub identity per account — there's no picker for multiple connected accounts. If two collaborators on the same project both connect their own GitHub accounts, whichever of them actually links the project is the one whose token is used for every push and pull afterward.

Self-hosting

If you're running TeXposit yourself and haven't configured a GitHub OAuth client, every GitHub button and tab is hidden automatically. Nothing depends on it being set up.

Two Ways to Start

Importing a repo as a new project: On the projects dashboard, click Import from GitHub and pick a repo from the dropdown. TeXposit clones it — keeping its real commit history rather than starting fresh — auto-detects the main .tex file, and opens the editor. The link created this way always uses the repo's default branch and is bidirectional ("Keep in sync both ways") from the start.
Linking an existing project: Open the project, go to Settings → GitHub, and either pick a repo you already have or create a new one without leaving TeXposit. Choose a direction — Back up to GitHub (TeXposit stays the only place you edit) or Keep in sync both ways (edits pushed to the repo come back into TeXposit) — and click Link. Linking a project to a public repo shows a warning that everything you publish will be visible to anyone.

A project can only be linked to one repository at a time, and a purely local project (one that was never a git repo, e.g. before it was linked to a local folder) can't be linked at all — there's no history for GitHub Sync to push.

Push

A background process checks every linked project roughly every 30 seconds and pushes if its history has moved since the last push. To skip the wait, use the Sync now button in Settings → GitHub. TeXposit never force-pushes: if GitHub has commits it doesn't know about, the push is rejected and the tab shows an error telling you to resolve it on GitHub, rather than silently overwriting anything. A failed push never interrupts editing — it just keeps retrying.

Pull

Pulling only happens on bidirectional ("Keep in sync both ways") links — a backup-only link never reads anything back. It runs on three triggers: a GitHub webhook when someone pushes to the repo, opening the project in the editor, and the manual Sync now button. A pull is always a fast-forward, never a merge: if the remote is ahead, TeXposit updates to match and refreshes the file tree in any open editor session without touching a file you currently have open. If both sides have changed since the last sync, the pull stops and reports the conflict rather than guessing — resolve it on GitHub's side, then Sync now once it's clean.

No merge tool

TeXposit doesn't merge or rebase diverged history. If a push is rejected or a pull reports a conflict, the fix happens on GitHub (or via a local git client against the same repo), not inside the editor.

Choosing What Gets Published

On a backup-direction ("Back up to GitHub") link, the Settings → GitHub tab has a Choose what gets published section: one glob pattern per line to exclude files, with a ! prefix to re-include something an earlier line excluded — the same convention as a .gitignore. A live preview shows how many of the project's files will actually be published as you edit the patterns, and a separate Save button stores them. Linking to a public repo pre-fills .texposit/** so your AI chat history isn't published by default; edit or clear it if you want it included.

This filtering isn't available on bidirectional links, since it works by rewriting the commit history that gets pushed, and a rewritten history can't be pulled back from safely. Your project's real history is never altered either way — only what leaves the door on a push.

Branch

A link syncs with a single branch, chosen when you link the project (the repo's default branch, pre-filled). There's currently no way to change a link's branch afterward short of unlinking and relinking — if you need to work against a feature branch, do that with a local git client against the same repo.

The GitHub Badge

A small GitHub icon on the projects dashboard means a project has a GitHub link, on either direction — it doesn't distinguish a healthy sync from one that needs reconnecting. For the actual status — last synced time, direction, and any error — check Settings → GitHub inside the project itself.

Disconnecting & Unlinking

Disconnecting your GitHub account from your profile stops all syncing but doesn't remove any project's link configuration — linked projects just show a "needs reconnect" state until you connect again. To remove a specific project's link entirely, use Unlink in that project's Settings → GitHub tab; this also removes the webhook TeXposit registered on the repo. Neither action touches the repository on GitHub itself.