Migrate from Git¶

In this tutorial you will bring an existing Git repository into TOVIO — full history, branches, and tags — with a single command. You'll see what carries over, what changes, and how to keep working with the muscle memory you already have. This works today with the runnable offline core.

Before you start

You'll want the tovio binary installed (install tutorial) and a Git repository on hand to import — a clone of one of your own projects is perfect for a first run.

What import does¶

tovio git import walks a Git repository's commit graph and builds TOVIO history from it, inside a freshly initialized TOVIO repository:

Every Git commit gets a fresh, stable Change ID (chg:…).
The original Git commit hash is recorded as provenance (in .tovio/git-import/commits.tsv), so nothing is lost and you can always trace a change back to where it came from.
Branches come across as lanes; tags come across as tags.
Your .gitignore is mapped to .tovioignore (nested ones are rebased onto the root, and the dot-prefixed paths your history tracks are re-included so nothing reads as deleted).

It is one-way: import reads your Git repo and never writes back to it, so your original is untouched and safe.

Step 1 — Import the repository¶

Import brings Git history into a TOVIO repository, so it needs one to exist first: make a new directory, initialize it, then point tovio git import at the local path of the Git repository (the source must be on disk — clone a remote first if it isn't).

mkdir my-project-tovio && cd my-project-tovio
tovio init
tovio git import ../my-existing-project

✓ Imported 1284 commit(s) from Git
  3 branch(es): develop, main, release/2.0 · now on `main`
  9 .tovioignore line(s) derived from the imported .gitignore file(s)
  3 dot-prefixed path(s) re-included so they stay tracked: !.editorconfig, !.github/, !.gitignore
  3 tag(s): v1.0, v1.1, v2.0
  Packed 41902 loose object(s) into packfiles
  Provenance (git hashes) recorded in .tovio/git-import/commits.tsv
  Run `tovio log` to see the imported history.

Import builds the history and refs but does not write the files into your working copy. Check the imported tip out, then look around:

tovio materialize
tovio log

Your history is there — now keyed by stable change IDs, with the original Git hashes carried along as provenance.

Your Git repo is untouched

Import only reads the source. The Git repository you imported from is exactly as it was — this is safe to run against a real project.

Import wants a fresh repository

tovio git import refuses to run in a repository that already has commits or lanes, so imported history never tangles with hand-made commits. To retry a partial import, initialize a clean directory and import again. Running it before tovio init prints the two-step remedy (TVO-CLI-003). Large imports repack their objects on the way in; pass --no-repack to skip that and run tovio gc --repack later.

Step 2 — Confirm what came over¶

tovio lane            # list lanes — your Git branches are here
tovio tag             # your Git tags
tovio log             # full history, with change IDs

What carries over	Notes
Full commit history	Every commit reachable from a local branch, in DAG order
Stable Change IDs	Assigned fresh on import — the identity that survives future rewrites
Original Git hashes	Recorded per change in `.tovio/git-import/commits.tsv`, for traceability
Branches and tags	Brought across as TOVIO lanes and immutable tags
`.gitignore`	Mapped to `.tovioignore`

Step 3 — Keep your Git muscle memory¶

You don't have to relearn everything on day one. TOVIO ships a git-compat layer: the Git commands whose habits are strongest are recognized, each does the right TOVIO thing, and each prints a gentle one-line note pointing you at the native verb.

tovio add .          # no-op — TOVIO tracks automatically; prints a note
tovio checkout main  # → tovio switch main, with a note

You type (Git habit)	TOVIO does	What it tells you
`tovio add`	Nothing — tracking is automatic	"TOVIO tracks changes automatically — there is no staging area. See `tovio status`."
`tovio checkout <name>` (`-b` creates it first)	`tovio switch <name>`	"`tovio switch` moves between branches."
`tovio push` / `tovio pull` (no arguments)	Prints the explicit form	"TOVIO unifies git push/pull as `tovio sync`; `clone`/`push`/`pull` are the explicit forms."
`tovio stash`	Nothing — your work is already a tracked change	"Your work is already a tracked change — see `tovio status`."

push / pull / sync are implemented

tovio push, tovio pull, and tovio sync are real commands over the shipped TLS network sync transport, not aliases: with a relay and repository id they transfer objects and refs, and a bare tovio push/tovio pull prints the hint above instead. Production multi-host deployment verification remains, but live remotes are supported.

These are training wheels that teach, not silent redirection. Once a native command is in your fingers, silence the notes:

tovio config set compat.git.notes off

A few things that are different on purpose¶

As you settle in, three Git habits change — all covered in the solo tutorial:

No git add / no staging area. Your working copy is always the current change.
You work in changes, land onto lanes. A lane is a destination, not where you live.
Recorded local mutations are undoable. tovio undo reverses the latest supported op-log entry, not just commits; it does not recall effects already observed by another system.

Going the other way, or syncing both

One-shot tovio git export <dir> and the explicit two-way tovio git bridge <remote> --bidirectional are implemented. The bridge uses disjoint namespaces and never force-pushes either side. See the migration guides.

What you learned¶

tovio git import brings a Git repo's full history, branches, and tags into a freshly initialized TOVIO repository in one command, assigning stable Change IDs and recording the original Git hashes.
Import is one-way and read-only on the source — your Git repo is untouched.
The git-compat layer keeps your muscle memory working while it teaches you the native verbs.

Next¶

You've got a real project in TOVIO. Start using it like one:

The daily loop, hands-on: A solo project, end to end.
The feature that makes the move worth it: Protect a secret.
The full command set: CLI reference.

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure