Version Control

Version control is how you make experimentation reversible. It matters even more when an agent can edit files.

Embedr includes Git-aware UI for project status, diffs, branches, commits, and history.

The Git button

The toolbar Git button shows the current branch and a small diff summary when files changed.

Open it to:

• initialize a repository,
• review changed files,
• stage and unstage,
• commit,
• inspect branches,
• fetch, pull, and push when remotes are configured.

Diffs

A diff answers "what changed?" Review diffs before compiling if the change is large, and always review before committing.

Look for:

• changed pin numbers,
• deleted setup code,
• new blocking delays,
• dependency changes,
• generated files that should not be committed,
• comments that no longer match code.

Checkpoints

Auto-checkpoints are Git commits created around AI-driven modifications when enabled. They make it easier to restore a previous state after an agent experiment.

Use checkpoints when:

• asking the agent to make several edits,
• trying a risky refactor,
• preparing classroom examples,
• touching hardware behavior.

Do not use checkpoints as a replacement for named commits. They are safety rails, not a project history style.

Branches

Use a branch for work that might take more than one session.

Examples:

• sensor-bringup,
• pcb-led-driver,
• workshop-cleanup,
• fix-upload-esp32.

Branches are useful when the agent is exploring one direction and you want main to remain stable.

A good AI review loop

1. Start from clean Git status.
2. Ask the agent for one bounded change.
3. Let it compile or run a check.
4. Review the diff.
5. Commit with a human-readable message.

If the diff is too large to review, the task was too broad.

Restore

Use restore carefully. Restoring a commit or discarding changes can remove work. Make sure you know whether the changes are uncommitted, committed, or on another branch.

If a project is important, create a branch before large restores.

Remote repositories

Embedr can work with remotes, but authentication still depends on your system setup. HTTPS may require tokens. SSH requires keys.

If fetch or push fails:

• verify the remote URL,
• try git fetch in the Terminal,
• check SSH agent or credential helper,
• make sure you have repository permissions.

What to commit in hardware projects

Commit files that express engineering intent:

• firmware source,
• embedr.yaml,
• platformio.ini,
• schematics source,
• useful datasheet markdown,
• wiring docs,
• test notes.

Do not commit build output unless there is a strong release reason.