Git Collaboration | ONDE Docs

Goal

One workspace. Many editors. Zero merge pain. Git-native. No server. No locks.

How Collaboration Works (User View)

Everyone edits markdown freely. Any editor. Any time.
No central database. No live sync. No file locking.
Changes merge through the journal. Git tracks the result.
onde lint = sync point. onde git commit = safe checkpoint.

The Git Workflow

onde does not replace Git. It wraps it safely.

What `onde` touches	What `onde` ignores
`.onde/` journal + cache	Your scripts, configs, assets
Changed `.md` files	Unrelated markdown (notes, drafts)
Auto-generated commit messages	Your custom git hooks, branches, remotes

Rule: onde only stages what it manages. Your repo stays yours.

`onde git commit` (What It Does)

One command. Safe. Predictable.

onde git commit

What happens:

Reads uncommitted journal changes.
Generates a scannable commit message.
Stages .onde/ + only changed markdown files.
Commits. Done.

No journal changes? Command skips silently. No empty commits.
Unrelated files edited? Not staged. Not touched.

Message examples:

onde: set task-882 status DOING→BLOCKED
onde: add task-895, fix Active Tasks[3]→5
onde: 23 changes (5 add, 12 set, 3 edge-add, 2 fix, 1 auto-id)

Concurrent Edits (Two People, Same File)

No conflict markers. No manual resolution.

Scenario: Alice edits status. Bob edits priority. Both save.

Alice runs onde lint → journal records status change.
Bob runs onde lint → journal records priority change.
Journal merges both automatically. Deterministic.
Markdown updates to reflect merged state.
Git sees clean line appends. Zero conflicts.

Rule: Edit freely. Lint to sync. Commit to lock.

Pull & Sync Flow

Remote changes landed? Sync before you work.

git pull
onde lint          # merges remote journal ops, updates your markdown
# continue editing

What lint does after pull:

Reads new journal entries from remote.
Merges them with your local state.
Updates markdown files to match merged truth.
Reports what changed. Clean exit.

Rule: Always onde lint after git pull. Never skip.

Recovery & Safety Nets

Mistakes happen. Recovery is one command.

Scenario	Fix
Accidentally deleted `tasks/` folder	`onde materialize` rebuilds from journal
Markdown looks broken after merge	`onde lint` heals it from journal
Want to see what changed remotely	`onde diff HEAD~3 HEAD` (graph-level diff)
Need to revert workspace to yesterday	`onde restore --at 2026-04-06 --reason "rollback"`
Journal cache feels stale	`onde materialize --check` verifies, `onde materialize` rebuilds

Rule: Journal = truth. Markdown = view. Delete view anytime. Rebuild safe.

Daily Team Checklist

Start of day:
  git pull
  onde lint

During work:
  Edit markdown freely
  onde lint (sync + validate)
  onde git commit (checkpoint)

End of day:
  onde lint
  onde git commit
  git push

Weekly hygiene:
  onde tree --over-budget
  onde organize --dirs --rename
  onde relink --to id
  git commit -m "Weekly workspace sync"

Common Traps & Fixes

Trap	Symptom	Fix
Commit without lint	Git shows messy markdown diff	Run `onde lint` first. Then commit.
Pull without lint	Files look stale or mismatched	`git pull` → `onde lint`. Always.
Manual git commit on `.onde/`	Message unclear, stages wrong files	Use `onde git commit`. Let it scope correctly.
Two editors change same property	Last writer wins	Expected. Deterministic. Check `onde history <id>` if needed.
Push breaks teammate’s lint	Remote ops not merged locally	Teammate runs `git pull` → `onde lint`. Heals instantly.

Deep Dives

Next Step: → Agent Integration (Optional but Powerful)