Getting Started
Let tm Create Your Project Clones
Run tm run <owner>/<repo> and let trusty-mpm clone the repository. Do not clone it by hand into a flat directory such as ~/code/<repo>, and do not run tm project init on an old checkout.
The canonical layout
tm keeps every managed project at one path:
~/trusty-mpm-projects/<owner>/<repo>/ # the base clone
~/trusty-mpm-projects/<owner>/<repo>/.worktrees/... # per-session worktrees
For example, bobmatnyc/trusty-tools lives at ~/trusty-mpm-projects/bobmatnyc/trusty-tools.
Why tm owns the clone
- One path per repository. The
<owner>/<repo>key gives the same path on every machine.tmcan derive the location from the repository name instead of from a path you chose. - Right account.
tmclones as theghaccount pinned for the project, else the account its[accounts]org map names for the owner, else your ambientgitcredential. The session then runs as that same account. A hand clone always uses the ambient credential. - Safe sessions. The base clone stays clean. Each session works in its own worktree under it, and
tminstalls the cross-branch push guard when it clones. - Wrong remotes fail loud. If a checkout at the canonical path has a different
origin,tmstops. It never re-points a remote.
A flat hand clone has none of this. Nothing ties it to an <owner>/<repo> key, so tm run <owner>/<repo> will not reuse it.
New project
tm run <owner>/<repo>
tm clones the repository (or checks the existing clone), prepares the session, and starts it in a tmux pane. The session appears in tm ls and tm sessions. A full repository URL works too, for hosts other than GitHub.
A dirty checkout does not block the run. tm skips the fast-forward, prints a warning that names the path, and starts the session anyway.
Existing flat or legacy checkout
Leave the old checkout where it is. tm does not move or adopt it. Do not run tm project init on it: the project control-plane spec marks that command deprecated in favour of tm projects register.
- Push or stash anything you want to keep in the old checkout.
- Run
tm run <owner>/<repo>. This creates the canonical clone next to your other managed projects. - Work from the canonical clone from now on.
- Delete the old checkout when you no longer need it.
Two cases look similar but are different:
- A no-origin local repository.
tm launchruns the session in that checkout itself. It is not refused. Use this for a scratch repository that has no remote. - An old per-session layout. Earlier versions kept full clones in per-session subdirectories under
~/trusty-mpm-projects/<owner>/<repo>/. If that directory has no.git,.base, or.worktreesentry,tmrenames it to<repo>.old-layout-backup-<timestamp>before it clones, and keeps your data there. If it has one of those entries,tmstops with an error and moves nothing. Remove or relocate the directory yourself.
Change the root
The default root is ~/trusty-mpm-projects. To move it, set workspace_root_template in ~/.trusty-tools/trusty-mpm/config.yaml, or export TRUSTY_MPM_WORKSPACE_ROOT. The order is TRUSTY_MPM_REPOS_ROOT, then TRUSTY_MPM_WORKSPACE_ROOT, then workspace_root_template, then the default. TRUSTY_MPM_REPOS_ROOT, if set, wins over both of the others. See config-convention.md for the precedence rules.