Coming from repo and git submodules

This page maps Google's repo tool and git submodules onto reprobuild workspaces, explains where they differ, and says when repo or submodules remain the better choice.

What carries over

• A manifest says which repositories belong together, where each is checked out and which branch it follows.
• Repositories are checked out side by side and stay separate git repositories, each with its own history and remote.
• One command acts on all of them: sync, status, or a command run in each.

Concept map

What works differently

The workspace and the build know about each other. A repository builds against the checkouts of its dependencies in the same workspace when they are in develop mode, so a change in a library reaches its users at the next build, without a publish step.

Each repository pins what it was built against. Instead of one manifest revision or a submodule commit in a parent repository, each repository commits its own repro.lock. A pre-push check refreshes it and refuses a push whose dependencies are not published.

Branches are named by role. A repository declares which of its branches is its mainline, its unstable branch and others, in branch roles. repro sync --mainline moves every repository towards its own mainline, whatever each one calls it, and repro workspace branch-roles prints what each role resolves to, without fetching anything.

A workspace can be forked. repro branch ../<directory> creates a second workspace next to the first, on a new branch, for parallel work.

When repo or submodules remain the better choice

• Submodules, when a parent repository has to record the exact commit of each child, and readers clone it with nothing but git.
• repo, when your workflow depends on Gerrit integration such as repo upload.
• Either, when the repositories do not build against each other and you only need them checked out together.

Next steps

• Join a workspace
• Work on a dependency's source
• Command equivalents