Working with Overleaf: a Git-based workflow
Overleaf's Git integration lets you clone an Overleaf project locally, run TeXRA's agents and latexdiff in VS Code or the terminal, and push commits back to Overleaf for your coauthors.
Works from the CLI too
The clone → edit → push loop below works in the terminal as well. After cloning, run agents with the texra CLI (e.g. texra run edit --input main.tex) instead of the VS Code panel, then commit and push as usual.
Prerequisites
- Overleaf account with Git access enabled for your project (check Overleaf plans).
- An Overleaf Git authentication token (starts with
olp_). Generate one from Account Settings → Git Integration. Read Overleaf's token documentation for step-by-step instructions. - Git installed locally. Install it using your platform's package manager:
- macOS:
brew install git(via Homebrew), or runxcode-select --installto get git as part of the Xcode Command Line Tools. - Windows: Download the installer from git-scm.com, or install via
winget install --id Git.Git -e. - Linux (Ubuntu/Debian):
sudo apt-get install git.
- macOS:
- TeXRA installed as either the VS Code extension or the
texraCLI (installation guide).
Workflow steps
The whole loop is a round trip: pull your project down from Overleaf, edit it locally with TeXRA, then push your commits back.
Clone or pull brings the project into VS Code, where TeXRA's agents do the editing; git push sends your committed changes back to Overleaf for your collaborators.
1. Clone your Overleaf project
Option A: use TeXRA's clone command (recommended)
- In VS Code, open the Command Palette (Ctrl/Cmd+Shift+P) and run TeXRA: Clone Overleaf/ShareLaTeX Project.
- Paste the Overleaf project URL or 24-character project ID when prompted.
- Enter your Overleaf Git token (it begins with
olp_). TeXRA saves it to~/.texra/secrets/so future clones can reuse it. - The command runs
git clonedirectly into your workspace root, so the cloned project becomes the repository you're working in. Make sure that folder is empty before starting.
Three steps: pick the command, enter the project URL or 24-character ID, then enter your olp_ token, which is saved in ~/.texra/secrets/ for next time.
Token storage: Reset the saved token at any time by removing its entry from
~/.texra/secrets/. The token is never written into the clone's remote URL: after cloning, TeXRA offers it to your Git credential helper (the macOS keychain or Git Credential Manager, for example) so later pulls and pushes sign in. Without a helper, Git asks for it; enter the token as the password.
Option B: use the TeXRA CLI
Pass either the Overleaf project URL or its 24-character project ID, and optionally the directory to create or clone into (the working directory when left out):
texra clone 0123456789abcdef01234567 ./projectThe CLI requests the Git token without displaying it and saves the token in TeXRA's local secret store. Later clones reuse the saved token. In scripts, --no-input disables the prompt; the command then requires a token saved by an earlier interactive invocation. Self-hosted ShareLaTeX project and Git URLs are accepted by the same command.
Option C: manual terminal fallback
- Overleaf: Go to your project > Menu > Git. Copy the Git clone URL (
https://git.overleaf.com/YOUR_PROJECT_ID).
- Local terminal: Go to the local directory you want and run:bashWhen prompted for a password, enter your Overleaf Git token (
git clone https://git.overleaf.com/YOUR_PROJECT_ID your-local-folderolp_…). For the username, enter any non-empty value (e.g.git).
2. Edit locally with TeXRA in VS Code
Open your-local-folder in VS Code and run your agents and programs (research, latexDiff, edit, merge, etc.) as usual. Optionally use LaTeX Workshop for local PDF previews (LaTeX compilation setup).
- Select files, agent, modelPick what to edit and which model runs
- Write instructionsDescribe the change in plain language
- Start taskRun the agent on your selection
- Review outputsInspect the r0/ revision in run storage
- latexdiff / mergeDiff, compare or merge edits from the LaTeXDiffs sheet
Each toolbar action in the local edit loop, from selecting files and writing instructions through Start task, reviewing outputs, and latexdiff/merge.
3. Commit local changes
As you work, commit changes often using VS Code's Source Control () or the terminal:
# Stage changes (e.g., all modified files)
git add .
# Commit with a descriptive message
git commit -m "Refine methodology section with TeXRA"4. Sync back to Overleaf
- (Recommended) Pull: Fetch and merge any changes made directly on Overleaf since your last pull:bashResolve any merge conflicts locally using standard Git tools.
git pull - Push: Upload your local commits to Overleaf:bashRefresh Overleaf in your browser to see the synced changes.
git push
Important considerations
- Merge conflicts: Pull changes from Overleaf before pushing your local work to keep conflicts small.
- Authentication: Git may re-prompt for Overleaf credentials. If your token expires, generate a new one from Overleaf account settings (read the token documentation).
- Large projects: Overleaf Git has size limits; keep them in mind for large projects.
Next steps
- Best practices: get more out of TeXRA.
- LaTeX Diff: change comparison in detail.
- Intelligent Merge: AI-assisted merging.