How mel works

No good abstraction should be without a full explanation of what has been abstracted. If you're an engineer or AI trying to figure your way out of some confusing scenario, hopefully this information can help:

This documentation explains what each mel command is doing under the hood, and you can get the same help by simply running mel explain <command>.

What mel is

Mel is a simple python script that runs ontop of git. It's not its own version control system, it just makes git easier to use with simpler commands, wording and focus on the majority workflow.

This means that if you ever get stuck, you can always fall back to git commands.

b / branch

Creates or switches to your personal workspace branch off the latest main and sets upstream. See main.

# Equivalent git
git fetch origin                         # if origin exists
git checkout -B <your-branch> origin/<main>  # or just <main> without origin
git push -u origin HEAD

save

Commits all changes, updates your branch with the latest main, then pushes. Confirmation before adding files can be controlled with require_add_confirmation. Update behavior uses rebase by default (see update_strategy).

# Equivalent git (default rebase)
git add -A
git commit -m "mel save @ <timestamp>"
git fetch origin
git rebase origin/<main>
git push

If you set update_strategy to merge, mel will fast‑forward merge instead of rebase:

# Alternative when update_strategy = "merge"
git add -A && git commit -m "mel save @ <ts>"
git fetch origin
git merge --ff-only origin/<main>
git push

update

Alias for sync. If you have uncommitted changes, mel will prompt to save or stash first, then update your branch from latest main via update_strategy.

# Rebase strategy (default)
git fetch origin
git rebase origin/<main>

# Merge strategy
git fetch origin
git merge origin/<main>

publish

Confirms, then fast‑forward merges your workspace branch into main, pushes main, rebases your branch back on top, pushes the branch, and runs hooks. Confirmation can be disabled via require_publish_confirmation. Teams should run tests via scripts or pre_publish hooks.

# Equivalent git (happy path)
# pre‑publish: run tests (project‑specific)
git checkout <main>
git pull --ff-only origin <main>
git merge --ff-only <your-branch>
git push origin <main>
git checkout <your-branch>
git rebase origin/<main>
git push

status

Shows ahead/behind versus main, dirty files, last commit summary, and then prints git status.

reset

Restarts your branch from the latest main: stashes any local changes, hard resets your branch to main, then force‑pushes. Guarded to prevent running on main.

git fetch origin
# if dirty, stash local changes for safety
git status --porcelain | grep . && git stash push -u -m "mel reset backup @ <ts>" || true
git reset --hard origin/<main>
git push --force origin <your-branch>

clear

Stashes your uncommitted changes (including untracked files) without touching your branch history. Use this to get a clean working tree; you can restore later with git stash pop.

git stash push -u -m "mel clear @ <timestamp>"

open

Opens the remote repository homepage in your browser. Uses your origin URL.

pr

Opens a prefilled PR compare URL (GitHub) for the current branch vs main.

diff

Shows staged and unstaged diff stats.

hooks

Optional arrays of commands that run before/after core operations. See hooks.

non‑interactive mode

Set MEL_YES=1 or pass --yes to auto‑confirm prompts. Affects publishing confirmation and file‑add confirmation when require_add_confirmation is enabled.