Version Control

Review, commit, sync, branch, stash, resolve conflicts and undo with Git inside Embedr, plus chat checkpoints and what to commit in a hardware project.

Embedr has the everyday Git workflow built in: review your changes, commit or amend, sync with a remote, switch and merge branches, resolve conflicts, stash, discard and undo. It covers a normal day of Git work without a terminal.

Rebase, cherry-pick, revert, tags, blame, bisect, submodules, Git LFS, worktrees and staging part of a file (hunks) are not in the app. Use Git in the Terminal for those.

Where Git lives

Place Use it for
Branch button in the bottom toolbar Opens the Git menu: changes, commit, sync, merge conflicts, branches. It shows the current branch and the lines added and removed.
Review Changes tab A diff of everything you have changed, with a discard button per file.
History & remotes (bottom of the Git menu) Opens the Version Control window: staging file by file, commit history, restoring a commit, branch management, remotes and stashes.

Start a repository

If the project is not a Git repository yet, the branch button reads Initialize Git. Open it and click Initialize Repository. Embedr creates the repository, adds a .gitignore with sensible defaults for Embedr projects, and makes the first commit. If the folder already had a repository with no commits, it just makes the first commit.

Commit

The Git menu's Changes header shows how many files changed, or Clean.

  1. Click Review to open the Review Changes tab and read the diff.
  2. Type a message in Commit message (⌘Enter)..., or click Generate to have one written from your changes.
  3. Click Commit, or press Cmd/Ctrl+Enter.

Commit in the Git menu stages and commits every change. To commit only some files, use the Version Control window (see Stage files one by one).

A toast confirms the commit with its short hash. If some files could not be added, the toast says Commit created with skipped files and names them.

Amend the last commit

Tick Amend last commit under the message box to fold your current changes into the previous commit. Its subject is shown next to the checkbox so you can edit it. The button changes to Amend.

Stage files one by one

In the Version Control window (History & remotes), the Changes view lists files grouped as staged and unstaged:

  • Click a file's stage button (Stage Changes / Unstage Changes) to move it.
  • Stage All Changes, Unstage All Changes and Discard All Changes act on the whole list.
  • Click Commit staged (or Cmd/Ctrl+Enter) to commit only what is staged.

Review changes

Review Changes opens from the Git menu's Review button or the + menu in the tab strip. It shows the diff of every changed file, staged and unstaged, with a discard button on each file. Review before you commit, and especially after an agent run:

  • changed pin numbers or peripheral assignments,
  • removed setup code,
  • new blocking delays,
  • dependency changes in platformio.ini or embedr.yaml,
  • generated files that should not be committed.

Discard changes

Discarding puts files back to the last commit. Embedr always asks first, and names what will be lost.

  • One file: the discard button on its row in Review Changes or the Version Control window.
  • Everything: Discard all changes… in the Git menu's ... menu (More change actions).

A file that was never committed is deleted, and the confirmation says it cannot be recovered. Files listed in .gitignore are never touched.

Undo the last commit

Undo last commit in the ... menu takes back the last commit and leaves its changes staged, so you can fix and commit again.

Undo and amend are only offered for a commit that has not been pushed. They are unavailable for:

Situation Reason shown
The commit is on the remote This commit is already pushed.
A merge is in progress Complete or abort the merge first.
Undoing the first commit The first commit cannot be undone.
Undoing a merge commit A merge commit cannot be undone here.

Sync with a remote

Below the commit box, the sync row shows the branch with ↑ commits to push and ↓ commits to pull, and one main button:

Button When What it does
Sync The branch tracks a remote branch Pulls, then pushes.
Publish branch The branch exists only on this computer Pushes it and sets it to track the remote.

Pull, Push and Fetch on their own are in the menu next to the button (More sync actions). Opening the Git menu also fetches quietly, at most every five minutes, so the behind count is current.

Pull always merges; it never rebases. If a pull hits conflicts, see Resolve conflicts.

If the project has no remote, the row says Add a remote under History & remotes to sync. Add one in the Version Control window under Branches → Remote & Sync: enter a remote name (such as origin) and the repository URL, then click Update / Add Remote. Save the remote before fetching, pulling or pushing. The same section has Fetch, Pull, Push and Remove.

Signing in to a remote

On desktop, Embedr uses the Git installed on your computer when there is one, so your SSH keys, credential helper and keychain work as they do in a terminal. Embedr never waits on a hidden password prompt.

If the remote refuses access, the Git menu asks for an Access token (and a username if your host needs one), then Try again.

  • For HTTPS remotes, tick Remember for host on this computer to store the token encrypted with your system keychain. It is kept for your user account on this computer, never in the project.
  • Forget saved token in Remote & Sync removes it.
  • Without Git installed, Embedr still works, but every remote needs an HTTPS URL and a token.

Use a personal access token with repository read and write access, not your account password.

Branches

The Git menu lists local branches, with a check next to the current one. Search branches... filters the list.

  • Click a branch to switch. If you have uncommitted changes that would be overwritten, Embedr asks whether to carry them with you: it stashes them, switches, then applies them on the new branch. If they do not apply cleanly, a Review migrated changes toast says what to check; stashes made this way appear in the stash list.
  • Branches under On remote exist only on the remote. Click one to create a local branch that tracks it.
  • New Branch... creates a branch from where you are and switches to it.

In the Version Control window, Branches has Create Branch, a Switch control, and Manage: pick a branch and choose Merge into current branch or Delete Branch. Both ask for confirmation.

Resolve conflicts

When a merge or pull changes the same lines as your branch, it stops with conflicts instead of failing. The Git menu replaces the commit box with Merge in progress and lists each conflicted file, described as Changed on both sides, Deleted here, changed on the other side, or Changed here, deleted on the other side.

For each file:

Button Effect
Keep mine Keeps your branch's version.
Use theirs Takes the incoming version.
Keep deleted / Delete it Shown when one side deleted the file.
Resolved You edited the file yourself; stages it as it is. Refused while conflict markers (<<<<<<<) remain.

Click a file name to open it in the editor.

Resolve with agent sends the list of conflicted files to the chat, asking the agent to keep the intent of both sides, remove every conflict marker and check the project still builds, without committing. You then review and finish the merge.

When every file is resolved, click Complete merge to commit it. Abort merge puts your files back to how they were before the merge started, including any conflicts you already resolved, after a confirmation.

Stash

A stash puts your uncommitted changes aside and returns your files to the last commit.

  • Stash changes in the Git menu's ... menu stashes immediately.
  • In the Version Control window, Branches → Stashes has Stash current changes with an optional note (What are you setting aside? (optional)) and a Stash button, followed by the list of stashes with the branch they came from and when.

Each stash has:

Button Effect
Pop Applies the changes and removes the stash.
Apply Applies the changes and keeps the stash.
Trash icon (Drop this stash) Deletes the stash, after a confirmation.

If a stash applies with conflicts, the Git menu shows Stash applied with conflicts and the stash is kept. Resolve the files with Keep committed, Use stashed or Resolved; there is nothing to complete afterwards.

History and restoring a commit

The Version Control window's Changes view lists the commit history under the working changes. Select a commit to see the files it changed and their diffs. Restore files brings the project's files back to that commit on the current branch, after a confirmation; your current staged and unstaged changes are overwritten. Files added after that commit are removed; files Git does not track are left alone.

Clone a repository

On the desktop home page, click Clone Repository.

  1. Paste the Repository URL (https://github.com/owner/repo.git or git@github.com:owner/repo.git).
  2. Under Clone into, choose a parent folder. The project folder is named after the repository.
  3. If the host asks, enter an Access token and username.
  4. Click Clone. When it finishes, the project opens.

Chat checkpoints

Checkpoints are separate from Git. With Enable Chat Checkpoints on (Settings → General, on by default), Embedr takes a snapshot of the project's files before each message you send to the agent. Snapshots are stored outside the project and never create commits.

To go back, click Restore checkpoint and edit message on your earlier message in the chat. After a confirmation, the files return to the snapshot, every later message in that thread is removed, and your message is put back in the composer to edit and resend.

Use checkpoints to undo an agent turn quickly. Use commits for history you want to keep and share.

Desktop and browser

Feature Desktop Browser
Commit, amend, review, discard, undo, branches, merge, conflicts, stash Yes Yes
Remotes Any remote your Git can reach, SSH or HTTPS HTTPS repositories on GitHub, GitLab and Bitbucket
Credentials Your installed Git's keys and helpers; tokens can be remembered A token each time a remote needs one
Stash new (untracked) files Yes, with Git installed No: new files stay in place
Clone a repository Yes No

What to commit in a hardware project

Commit the files that describe the design:

  • firmware source (src/, include/, lib/),
  • embedr.yaml and platformio.ini,
  • hardware source: pcb/ .zen files and the KiCad project, schematic and board files,
  • mechanical sources under mechanical/,
  • datasheet notes, wiring docs and specs you want to keep.

Leave out build output and local state. A new repository's .gitignore already excludes them:

# PlatformIO
.pio/
# Embedr local state
.embedr/
.embedr_chat/
.embedr-board/
# KiCad local state and backups
*.kicad_prl
*-backups/
fp-info-cache
# Secrets
.env
.env.*

A good loop with the agent:

  1. Start from a clean working tree (the Git menu says Clean).
  2. Ask for one bounded change.
  3. Let the agent build or run a check.
  4. Open Review Changes and read the diff.
  5. Commit with a message that says what changed and why.

If the diff is too big to review, the request was too broad.