Skip to content
riggerrigger

adopt

rigger adopt <ROOT> [--hubs <DIR>] [--check] [--json]

Walks a directory and records the checkouts in it - a child with a .git inside - as projects. Where a hub of the same name sits under --hubs, it is imported; git is read for what shipped, as sync would. The three commands a project used to take, once for the line.

Terminal window
$ rigger adopt C:\dev --hubs C:\notes\Projects
alpha  recorded     hub: 12 versions, 31 tasks, 40 diary entries, 4 files of prose new   git: 9 versions shipped, 40 changes read
beta   recorded     hub: 4 versions, 9 tasks, 6 diary entries, 3 files of prose new   git: 2 versions shipped, 11 changes read
gamma  no hub


3 repositories: 2 recorded, 0 known, 1 without a hub, 0 skipped; 2 hubs read.

One level only. A line keeps its repositories side by side, and a walk that went deeper would find vendored trees and worktrees and call them projects. A directory without a .git is not a project and is not mentioned.

Which hub is whose

Section titled “Which hub is whose”

--hubs names a directory whose children are hubs, one per project, under the project’s name: C:\notes\Projects\alpha is the hub of the checkout C:\dev\alpha. That is where the hubs of a notes vault live, nowhere near the repositories they describe, and guessing a hub beside the repository would read nothing. A directory with the right name and none of the files a hub is read from is not a hub.

With --hubs, the hub is what makes a checkout one of the line. A directory of repositories holds strays - an experiment, a fork kept for reading, a plugin of another product - and recording every one of them would put a dozen projects nobody works on into every list. A checkout without a hub is named and left alone. Without --hubs, every checkout is recorded.

The record remembers where each hub is, so that doctor --hubs and export can find it later.

Running it again

Section titled “Running it again”

A project already recorded is not recorded twice; its hub and its tags are read all the same. So this is the command to run when the line has grown: the new checkout is recorded, the rest say known, and nothing that was quiet is reported as news.

Terminal window
$ rigger adopt C:\dev --hubs C:\notes\Projects
alpha  known        hub: nothing new   git: nothing new
beta   known        hub: nothing new   git: 1 version shipped, 3 changes read
delta  recorded     hub: 2 versions, 5 tasks, 3 diary entries, 2 files of prose new   git: nothing new
gamma  no hub


4 repositories: 1 recorded, 2 known, 1 without a hub, 0 skipped; 3 hubs read.

A checkout whose name is already taken by a project at another path is skipped and said, rather than recorded under a name that would lie about where it is:

alpha  skipped
       a project named 'alpha' is recorded at D:\old\alpha

--check

Section titled “--check”

Says what would be recorded and where a hub was found, and writes nothing:

Terminal window
$ rigger adopt C:\dev --hubs C:\notes\Projects --check
alpha  would record hub: found
beta   would record hub: found
gamma  no hub


3 repositories: 2 would be recorded, 0 known, 1 without a hub, 0 skipped; 0 hubs read.
Nothing was written. Run again without --check to record them.

JSON

Section titled “JSON”

adopt --json prints an array with one row per checkout.

Field Type Meaning
[] object One checkout.
[].name string The project’s name, taken from the directory.
[].path string The path of the checkout.
[].status string recorded, known, no-hub (a hubs directory was given and holds no hub of this name) or skipped.
[].why string or null Why a checkout was skipped; null for every other status.
[].hub string or null The path of the hub that was found; null when there is none.
[].versions_added integer Versions read from the hub.
[].tasks_added integer Tasks read from the hub.
[].diary_added integer Diary entries read from the hub.
[].prose_files integer Files whose prose was taken in.
[].tasks_dropped integer Tasks struck from the hub since it was last read.
[].versions_dropped integer Versions struck from the hub since it was last read.
[].shipped integer Versions a tag proved shipped.
[].changes_read integer Changes read from commit messages.
[].warnings array Things noticed and gone on from.
[].warnings[] string One warning.
Section titled “Related”
  • project add - one project at a time, with a name of your choosing.
  • import - what reading a hub does.
  • sync - what reading git does.
  • skill - the other half of moving a project onto rigger.