gg

gg is the unified Dart CLI for Dart and Flutter development at every scale — from running pre-commit checks in a single package to orchestrating commits, pushes, reviews and publishes across all repositories of a ticket.

It is a thin CLI shell that combines three backend packages:

Package	Scope	Purpose
`gg_one`	a single Dart/TypeScript repo	pre-commit checks (analyze, format, test, coverage, …)
`gg_multi`	a multi-repo ticket workspace	run commands across all repos of a ticket in dep order
`helix`	the DNA of a single repo	instantiate configs, docs, scripts and skills from DNA packages

gg detects where you run it:

Inside a gg ticket workspace (a directory tree containing .ocean/ — or the legacy .master/, renamed automatically — or tickets/) → gg <command> runs gg_multi by default.
Inside a standalone Dart or TypeScript project (a directory tree with pubspec.yaml, package.json or tsconfig.json) → gg prints a message asking you to use gg one <command> … explicitly.

Installation

dart pub global activate gg

After installation the gg executable is available globally.

Command Overview

gg
├── one  <subcommand>      Single-repo mode (gg_one)
├── dna  <subcommand>      DNA engine (helix)
├── can  <commit|push|publish|review>
├── did  <commit|push|review>
└── do   <commit|push|review|publish|claude|code|
          create|init|add|rm|maintain|
          ls <repos|organizations|deps|tickets>|…>

can, did, do and ls are the gg_multi commands, registered directly at the root: inside a gg ticket workspace gg do commit runs gg_multi's do commit. In a standalone project these commands abort with a message asking you to run gg one <cmd> … instead, and outside of any recognized project gg aborts with a hint explaining both options. (gg multi <cmd> still works as a hidden alias for the root commands.)

When to use `gg one`

Use gg one when you are working in exactly one Dart or TypeScript project — for example a freshly cloned package, a library you maintain on its own, or a repo that is not part of a ticket workspace.

gg one is a re-export of the gg_one package and offers the following subcommands:

Command	Purpose
`gg one check analyze`	static analysis
`gg one check format`	formatting check
`gg one check`	run the full local check pipeline (analyze + format + tests + …)
`gg one can commit`	verify the repo is ready to commit
`gg one do commit -m "…"`	commit after checks pass
`gg one can push`	verify the repo is ready to push
`gg one do push`	push after checks pass
`gg one did commit`	report what was committed since the last reference state
`gg one info`	print project metadata gg_one detected

gg one … is always explicit: in a standalone project a plain gg can commit or gg do push does not run anything but prints a message asking you to use gg one instead. This also works inside a ticket workspace when you want to run gg_one against a single repo (where gg can/gg do runs gg multi).

When to use `gg dna`

gg dna is a re-export of the helix package — the DNA engine. It resolves the DNA packages a repo declares as dev-dependencies (dna_base, dna_dart, dna-ts, …) and instantiates their content — configs, docs, scripts and agent skills — into the repo:

Command	Purpose
`gg dna init`	place the DNA test that instantiates the project DNA on every test run

Like gg one, gg dna works on a single repo, and it therefore runs in both modes: inside a ticket workspace and in a standalone project. helix remains available as its own executable — gg dna <cmd> and helix <cmd> do the same thing.

Workspace commands (`gg_multi`)

Inside a gg ticket workspace the gg_multi commands drive operations across all repos of a ticket — they run by default, directly at the root. See the gg_multi README and handbook.md for the full command surface; the most important ones are:

Command	Purpose
`gg do init workspace`	initialise the workspace
`gg do add <target>`	add a repo, a regexp match or a whole org to the workspace / ticket
`gg do create ticket <id>`	create `tickets/<id>/` with a `.ticket` file
`gg do code`	open the ticket in VS Code
`gg can commit`	check whether all ticket repos can commit
`gg do commit -m "…"`	commit in every ticket repo in dependency order
`gg can push` / `do push`	check / merge main into and push every ticket repo
`gg do review`	push, open pull requests and record the review
`gg did review`	report whether the current state was reviewed
`gg do publish`	publish every publishable package of the ticket
`gg do ls repos`	list repos in the ocean
`gg do claude`	generate an aggregated `CLAUDE.md` for the ticket

Step-by-step: working on a ticket end-to-end

The following walkthrough covers the typical lifecycle of a feature ticket from setup to publish. All commands assume gg is installed globally.

0. One-time project setup

mkdir my_project
cd my_project
gg do init workspace                     # initialise workspace
gg do add https://github.com/my-org      # add all repos of an org

gg do init workspace and gg do add are gg_multi workspace commands and run directly at the root.

1. Create a ticket workspace

cd my_project
gg do create ticket PROJ-123 -m 'Simplify login flow'
cd tickets/PROJ-123

This creates tickets/PROJ-123/ and writes a .ticket file with the ticket id and description.

2. Add the repos you need

gg do add app_core ui_core
gg do add "ui_.+"                        # every ocean repo named ui_…

A target may be a regular expression selecting repositories the ocean already holds. It is anchored, so gg do add gg adds the repository named gg and not every name containing it, and a target matching no ocean repo is treated as a name or url exactly as before.

Local dependencies are added automatically, and packages are localised inside the ticket so that intra-workspace edits resolve to local paths.

3. Open the ticket in VS Code (optional)

gg do code

4. Develop, run checks, iterate

Inside any individual repo of the ticket you can fall back to single-repo checks via gg one:

cd app_core
gg one check                    # full local pipeline for app_core only

5. Commit across all ticket repos

cd ../..                        # back to tickets/PROJ-123
gg can commit                   # verify every repo is commit-ready
gg do commit -m 'Simplify login flow'

gg can commit runs the full check pipeline (analyze, format, tests) in every repo in dependency order and aborts on the first failure.

6. Review

gg do review

do review merges the main branches into the feature branches, pushes every repo, opens a pull request per repo (printing the urls) and records the review — the repos keep their local path references; a reviewer recreates the setup via gg do import ticket.

7. Iterate on review feedback

gg do commit -m 'Address review comments'
gg do push

do push merges the main branches into the feature branches and pushes every repo, updating the open pull requests. It also works on its own at any time — gg do review simply runs it automatically.

8. Publish (when approved)

gg can publish
gg do publish

Publish should be triggered manually by a human after review approval. It refuses to run when the current ticket state was not reviewed (gg did review) — commits made after the last review require another gg do review first.

Non-interactive publish via `--config`

Both backends understand --config <path> for do publish. Pass a .gg-publish.json file to predeclare merge messages and version increments so the release runs prompt-free (handy in CI):

gg do publish --config .gg-publish.json

Minimal schema (top-level fields apply to every repo; the optional repos block lets you override per repo in workspace mode):

{
  "version_increment": "patch", // "patch" | "minor" | "major"
  "merge_message": "Default merge message",
  "repos": {
    "app_core": {
      // optional per-repo override
      "version_increment": "minor",
      "merge_message": "app_core: new public API",
    },
  },
}

gg looks for <configArg> as given (relative to the current directory, or absolute), then under the ticket directory in workspace mode, or under <repo>/.gg/ in single-repo mode. A missing required field aborts the run — no silent fall-back to a prompt.

See the gg_multi and gg_one READMEs for the full schema and lookup rules.

9. Generate an aggregated CLAUDE.md (optional)

gg do claude

Concatenates each repo's CLAUDE.md (in dependency order) into a single CLAUDE.md at the ticket root so Claude Code has full workspace context.

Getting help

Every command supports -h / --help:

gg -h
gg do -h
gg do commit -h
gg one -h

gg and gg -h list all gg_multi commands plus gg one.

License

gg is licensed under the terms specified in the LICENSE file.

gg

Installation

Command Overview

When to use `gg one`

When to use `gg dna`

Workspace commands (`gg_multi`)

Step-by-step: working on a ticket end-to-end

0. One-time project setup

1. Create a ticket workspace

2. Add the repos you need

3. Open the ticket in VS Code (optional)

4. Develop, run checks, iterate

5. Commit across all ticket repos

6. Review

7. Iterate on review feedback

8. Publish (when approved)

Non-interactive publish via `--config`

9. Generate an aggregated CLAUDE.md (optional)

Getting help

License

Libraries

gg package

gg

Installation

Command Overview

When to use gg one

When to use gg dna

Workspace commands (gg_multi)

Step-by-step: working on a ticket end-to-end

0. One-time project setup

1. Create a ticket workspace

2. Add the repos you need

3. Open the ticket in VS Code (optional)

4. Develop, run checks, iterate

5. Commit across all ticket repos

6. Review

7. Iterate on review feedback

8. Publish (when approved)

Non-interactive publish via --config

9. Generate an aggregated CLAUDE.md (optional)

Getting help

License

Libraries

gg package

When to use `gg one`

When to use `gg dna`

Workspace commands (`gg_multi`)

Non-interactive publish via `--config`