gg_multi library

Classes

AddCommand

Command to add a repo or all repos of an organization to ocean+ticket. In ticket mode it also auto-clones transitive deps and re-localizes refs. Use --force to overwrite an existing repo in the ocean. --organization may be given multiple times to add all repos of several organization folders of the ocean at once. --no-localize copies the repos without rewriting their references to local paths. --no-transitive copies only the requested repos and leaves the repos between them in the dependency graph out of the ticket.

AzureDevOpsPlatform

Azure DevOps implementation of GitPlatform.

CanCommitCommand

Command to check if all repos in the ticket can be committed.

CanPublishCommand

Command to check if all repos in the ticket can be published.

CanPushCommand

Command to check if all repos in the ticket can be pushed.

CanReviewCommand

Command to check if all repos in the ticket can be reviewed.

CodeCommand

Command to open all repos (or a single repo) under a ticket in VS Code.

CreateCommand

Command to create resources such as tickets.

DidCommitCommand

Command to check if all repos in the ticket were committed.

DidPushCommand

Command to check if all repos in the ticket were pushed.

DidReviewCommand

Command to check whether the current ticket state was reviewed.

DoCheckoutCommand

Reproduces a whole ticket from a ticket.json.

DoClaudeCommand

Creates a ticket-level CLAUDE.md file from all repositories in a ticket.

DoCommitCommand

Command to commit changes across all repositories in the current ticket.

DoConfigurePublishCommand

Interactively builds the .gg/gg-publish.json publish configuration for the current ticket, asking for the version increment and merge message of every repo that needs a release.

DoExecuteCommand

Command that executes a shell command in all repositories of the current ticket in the order of the processing list.

DoPublishCommand

Command to publish all repos in the ticket.

DoPushCommand

Command to push changes across all repositories in the current ticket.

DoReviewCommand

Command to review all repos in the ticket.

DuplicateRepoCleanup

Moves the folders a repository rename left behind out of a workspace.

EnsureInRegistry

Makes sure at least one version of a repo's package is available on its registry (pub.dev for Dart/Flutter, npm for TypeScript) before the repo is published.

ExecCommand

Command that groups the things gg can execute across the ticket repos.

GgMulti

The command line interface for GgMulti

GitHandler

Typedef for a process runner function. A class responsible for cloning git repositories and performing Git/utility operations.

GitHubPlatform

GitHub implementation of GitPlatform.

GitPlatform

Interface for Git platforms like GitHub, Azure DevOps, GitLab.

GraphCommand

Writes the dependency graph of the current workspace to stdout.

GraphEdge

One directed edge of the dependency graph.

GraphNode

One node of the dependency graph.

ImportCommand

Command that groups the things gg can import into the workspace.

InitCommand

Command that groups the things gg can initialize.

InitWorkspaceCommand

Command to initialize the ocean

ListCommand

Command to list items from the ocean. If no subcommand is provided, it asks the user to choose.

ListDepsCommand

Command to list dependencies of a project from the ocean.

ListOrganizationsCommand

Command to list all organizations from repos in the ocean.

ListReposCommand

Command to list all repositories in the ocean.

ListTicketsCommand

Command to list all tickets and their descriptions.

MockCanCommitCommand

Mock for CanCommitCommand

MockCanPublishCommand

Mock for CanPublishCommand

MockCanPushCommand

Mock for CanPushCommand

MockCanReviewCommand

Mock for CanReviewCommand

MockDidCommitCommand

Mock for DidCommitCommand

MockDidPushCommand

Mock for DidPushCommand

MockDidReviewCommand

Mock for DidReviewCommand

MockDoClaudeCommand

Mock for DoClaudeCommand

MockDoCommitCommand

Mock for DoCommitCommand

MockDoConfigurePublishCommand

Mock for DoConfigurePublishCommand

MockDoPublishCommand

Mock for DoPublishCommand

MockDoPushCommand

Mock for DoPushCommand

MockDoReviewCommand

Mock for DoReviewCommand

MockEnsureInRegistry

Mock for EnsureInRegistry

MockGraphCommand

Mock for GraphCommand

MockPublishPlanner

Mock for PublishPlanner

MockPublishSkipCheck

Mock for PublishSkipCheck

MockRepoFreshness

Mocktail mock

MockTicketState

Mocktail mock for TicketState.

MockUpgradeDepsCommand

Mock for UpgradeDepsCommand

NpmRegistryChecker

The npm counterpart of PubDevChecker: checks whether published versions are visible on npm, backed by gg_lang's RegistryWaiter over an NpmRegistry (npm view <name> version).

Organization

Represents an organization with id, name, url, and an optional project name.

OrganizationRepoLists

The repositories the registered organizations currently offer, asked for once per organization and run.

OrganizationUtils

A utility class to manage organizations associated with the ocean. Caches entries in a buffer.

PackagePublishInfo

Describes how a package is published.

ParseResult

Result of URL parsing.

PubDevChecker

Checks whether published versions are visible on pub.dev, backed by gg_lang's RegistryWaiter over a PubDevRegistry.

PublishPlan

The outcome of PublishPlanner.plan.

PublishPlanEntry

What a publish run will do with one repository of a ticket.

PublishPlanner

Decides what a ticket's publish run does with each of its repositories, and collects the answers the run needs — in one pass, in dependency order.

PublishPlanWording

The user-facing wording of a planning pass.

PublishSkipCheck

Decides whether a ticket repository needs to be published at all.

PublishSkipDecision

The outcome of PublishSkipCheck.get for one ticket repository.

RemoveRepoCommand

Deletes repositories from the ticket the command is invoked in.

RemoveTicketCommand

Closes one or more tickets: deletes the remote feature branches of their repositories and moves each whole ticket — repositories as they are, plus ticket.json, .gg/ and the .code-workspace file — to <root>/.trash/<ticket>.

RepoFolderResolver

Resolves repository folders in a workspace. A folder is matched by its exact name, then by its manifest package name (for cross-language bridge repos whose folder name differs from the package name), then by its git remote url.

RepoFreshness

Brings a repository to the state of the remote branch it tracks.

RepoIdentity

What a checkout says it is, independent of the folder it lies in.

RepoInfo

A class holding repository information.

RepoPublishPlan

The answers PublishPlanner.configureRepo collected for one repository, plus the registry baseline its increment preview was based on.

Repository

Represents a repository entry provided by a Git platform.

RmCommand

Command group for removing things from the workspace: rm repo <name…> deletes repositories from the current ticket — never from the master workspace — rm ticket closes the current ticket by moving it to the trash.

TicketCommand

Command to create a ticket folder and save ticket data as JSON.

TicketJson

The content of a ticket.json: the ticket id, its description and the full list of repositories (with git URLs) that make up the ticket.

TicketRepo

One repository entry of a TicketJson marker.

TicketState

Stores and retrieves cached success state of ticket-level commands.

Trash

The trash workspace <root>/.trash, the sibling of .ocean and of the ticket folders that holds everything gg removed from a ticket.

UpdateOceanCommand

Brings the ocean in sync with the git platforms.

UpgradeDepsCommand

Command to upgrade the dependencies of all repos in the current ticket.

UrlParser

Unified URL parser for different git platforms.

VSCodeLauncher

Provides logic to open a directory or workspace file in VS Code via the command line.

WorkspaceUtils

Utility functions that deal with the location of workspaces on disk.

Enums

RepoBlocker

Why a repository was not brought to the state of its remote main branch.

Constants

claudeClaudeMd → const String

Begin of generated CLAUDE.md

claudeCodeStandards → const String

code standards to be included in generated CLAUDE.md

claudeCommands → const String

command instructions to be included in generated CLAUDE.md

codeWorkspaceLaunch → const Map<String, Object?>

The launch configurations every ticket workspace carries.

codeWorkspaceSettings → const Map<String, Object?>

The settings every ticket workspace carries.

colorOff → const String

SGR sequence switching the terminal back to its default colors.

ggMultiLegacyMasterFolder → const String

The former name of ggMultiOceanFolder; auto-renamed at the next start

ggMultiLegacyTicketFolder → const String

The folder tickets used to be stored in.

ggMultiOceanFolder → const String

The ocean folder holding the pristine clones of all repos

ggMultiTrashFolder → const String

The trash folder beside .ocean that holds removed tickets and repos

gitattributesCommonLines → const String

The lines gg and the ticket workflow require in every repository's .gitattributes file, no matter which language it is written in.

gitattributesLockFilesByManifest → const Map<String, List<String>>

The lock files that are kept from the current branch instead of being merged textually, mapped to the manifest that makes them relevant.

legacyPrePushMarker → const String

Marker that identifies a pre-push hook as one gg installed itself.

legacyTicketJsonRelativePaths → const List<String>

Legacy locations of the ticket marker inside a repository.

pubspecOverridesFileName → const String

The file gg_localize_refs writes the local path overrides to.

ticketJsonFileName → const String

Name of the ticket description file inside the ticket folder.

workspaceDnaLayer → const String

The DNA layer every workspace gets: the gg workflow guides, the skills and the managed CLAUDE.md block.

workspaceLicense → const String

The LICENSE placed in the workspace root. The DNA build insists on one, and a workspace is no package: it says so instead of licensing anything.

Properties

ggCliVersion ↔ String

The version of the gg CLI that stamps and checks .ticket.json markers.

getter/setter pair

oceanMigrationLog ↔ GgLog

The log sink migrateMasterFolderToOcean uses when no GgLog is passed.

getter/setter pair

Functions

addRepositoryHelper({required String targetArg, required GgLog ggLog, required GitHandler gitCloner, GitHubPlatform? gitHubPlatform, AzureDevOpsPlatform? azureDevOpsPlatform, required String workspacePath, bool force = false, bool logIfAlreadyAdded = true, Future<void> onRepoAdded(String repoName)?, SelectOrganization? selectOrganization, String? failureHint, OrganizationRepoLists? repoLists}) → Future<void>

Helper function to add a repository given a target argument. It supports various formats like URLs, SSH links, and plain names. For organization URLs, it fetches all repositories and clones them.

anyRepoHasAnswers({required Iterable<Directory> repoDirs, required Directory ticketDir}) → bool

Whether any repository of the ticket has publish answers recorded.

anyRepoHasStatus({required Iterable<Directory> repoDirs, required Directory ticketDir}) → bool

Whether any repository of the ticket carries the given status.

azureCloneUrl(Uri uri, ParseResult parsed) → String?

The clone url of the Azure DevOps repository parsed names, rebuilt from its parts in the form Azure serves: https://dev.azure.com/<org>/<project>/_git/<repo> or, on the legacy host, https://<org>.visualstudio.com/<project>/_git/<repo>.

azureSshBase(String baseUrl) → String?

baseUrl as an Azure DevOps SSH base, [e-mail]:v3/…/, or null when it does not point at the Azure SSH host.

buildTicketJson({required Directory ticketDir, required Iterable<Directory> repoDirs}) → TicketJson

Builds a TicketJson for the ticket at ticketDir from repoDirs.

cleanUpTicket({required Directory ticketDir, required List<Directory> repoDirs, required bool deleteRemoteBranch, required GgLog ggLog, required GgLog taskLog, ProcessRunner? processRunner}) → Future<void>

Closes a finished ticket: deletes the remote feature branches, then moves the whole ticket folder into <root>/.trash/<ticket>.

copyDirectory(Directory source, Directory destination, {Set<String> skipNames = const {'node_modules', 'publish_config.json', 'publish_state.json', 'gg-publish.json', '.gg-publish.json', '.ticket.json', 'ticket.json', '.gg_localize_refs_publish_to_backup.json'}}) → Future<void>

Recursively copies source to destination.

defaultReadManifestVersion(Directory repoDir) → Future<String?>

The default ReadManifestVersion — asks gg_lang for whichever manifest the repository carries. Returns null when there is none, or none with a version.

defaultSelectOrganization(String repoName, List<Organization> organizations) → Future<Organization?>

Asks the user which organization a repository should be taken from.

editMessage(String initialMessage, {required String prompt, required String subject, required String hint}) → Future<String?>

Opens the interactive message editor with initialMessage and returns what the user leaves in the buffer.

ensureLockFilesNotIgnored({required Directory repoDir, required GgLog ggLog}) → bool

Ensures .gitignore of repoDir does not exclude any of the lock files lockFileNamesFor reports for it. Returns true when the file was changed.

existingCheckoutOf({required String workspacePath, required Directory clone}) → Directory?

The checkout workspacePath already holds of the repository just cloned into clone, or null when clone is the only one.

extractRepoName(String repoUrl) → String?

Extracts the repository name from a git URL supporting:

fetchDependencyRepoUrl(String packageName, {ProjectType type = gg.ProjectType.dart, Future<Response> packageFetcher(Uri)?}) → Future<String?>

Fetches the repository URL for a dependency from its registry: pub.dev for Dart/Flutter, the npm registry for TypeScript. Returns the URL if found, otherwise null.

getAllRepoInfos(String oceanWorkspacePath) → Future<List<RepoInfo>>

Returns list of repository information for repos in oceanWorkspacePath.

getPubspecFromWorkspace({required String targetArg, required String workspacePath, required GgLog ggLog}) → Pubspec?

Retrieves the Pubspec for a repository in the ocean. Returns null if pubspec.yaml is not found or parsing fails.

getRepoInfo(String repoPath) → Future<RepoInfo>

Returns repository information for the repository at repoPath.

gitattributesRequiredLinesFor(String repoPath) → List<String>

The lines .gitattributes of the repository at repoPath must contain.

helixDnaRunner(GgLog ggLog) → RunDna

The gg dna runner used outside of tests: helix's own commands, with the prompts of the gg suite — what gg dna itself runs.

helixSelectPrompt({required String prompt, required List<String> options}) → Future<int>

Answers the questions of helix through the prompts of the gg suite — the same menus gg do publish draws, and in an embedded gg whatever the embedder assigned to GgPrompts.current.

installGitattributes({required Directory directory, required GgLog ggLog, SortedProcessingList? sortedProcessingList, ProcessRunner? processRunner}) → Future<void>

Ensures a .gitattributes file containing all lines gitattributesRequiredLinesFor returns for the repository exists in every repository of the ticket directory lies in, and that the merge=ours driver is configured locally.

installRepoDependencies({required Directory dir, required String repoName, required GgLog ggLog, required ProcessRunner processRunner, bool upgradeDart = false}) → Future<void>

Installs dependencies for every package manager the repo in dir uses.

isAzureWebHost(String host) → bool

Whether host is one of the hosts Azure DevOps serves its web and clone URLs from: dev.azure.com or the legacy <org>.visualstudio.com.

legacyTicketPublishConfigFile(Directory ticketDir) → File

The legacy ticket-level publish configuration of ticketDir — <ticket>/.gg/gg-publish.json, or the even older <ticket>/.gg-publish.json when only that one exists.

loadTicketPublishState(Directory ticketDir) → PublishState

The ticket-wide run state of ticketDir — currently the delete-the-ticket answer, which belongs to no single repository.

loadTicketRepoPublishFiles({required Directory repoDir, required Directory ticketDir}) → RepoPublishFiles

Reads the publish files of repoDir, falling back to what the ticket in ticketDir recorded before the per-repo split.

lockFileNamesFor(String repoPath) → List<String>

The lock file names that must be committable in the repository at repoPath — one entry per language the repository actually uses.

matchOceanRepoNames(String target, Iterable<String> oceanRepoNames) → List<String>

The names in oceanRepoNames that target selects when read as a regular expression, sorted so a run is reproducible.

migrateMasterFolderToOcean({required String rootPath, GgLog? ggLog}) → bool

Renames the legacy <root>/.master folder to <root>/.ocean and an existing <root>/.trash/.master to <root>/.trash/.ocean.

migrateTicketToFlatFolders({required String ticketPath, required GgLog ggLog}) → List<String>

Moves every repository of the ticket ticketPath out of its organization folder up into the ticket itself (<ticket>/<repo>).

migrateToOrgFolders({required String workspacePath, required GgLog ggLog}) → List<String>

Moves every repository that still sits directly in workspacePath into a folder named after the organization of its git remote (<workspace>/<org>/<repo>).

organizationsOwningRepo({required String repoName, required String workspacePath, required GitHandler gitCloner, OrganizationRepoLists? repoLists}) → Future<List<Organization>>

Returns the known organizations of workspacePath that own a repository named repoName, in the order they are registered.

readTicketDescription(Directory ticketDir) → String?

Reads the trimmed description from <ticketDir>/ticket.json, or returns null when the file is missing, is not a JSON object, is malformed, or carries an empty description.

readTicketJson(Directory ticketDir) → TicketJson?

Reads <ticketDir>/ticket.json, or returns null when the file is missing or malformed.

removeDependencyOverrides({required Iterable<Directory> repoDirs, required Set<String> packageNames}) → List<Directory>

Removes packageNames from the localized overrides of every repo in repoDirs — the dependency_overrides of pubspec_overrides.yaml (Dart) and the overrides of pnpm-workspace.yaml (pnpm-managed TypeScript) — and returns the directories whose files were changed.

removeLegacyGitHooks({required Directory repoDir, required GgLog ggLog}) → bool

Removes the obsolete gg-generated pre-push hook from repoDir.

repoHasPublishStepProgress(Directory repoDir) → bool

Whether repoDir's own .gg/publish_state.json records completed publish steps — i.e. gg do publish already did irreversible work in that repo.

repoUrlOfOrganization(Organization org, String repoName) → String

Returns the clone url of repoName within org.

runWithLimit<T>(Iterable<T> items, int maxParallel, Future<void> task(T item)) → Future<void>

Processes items with task, running up to maxParallel tasks at a time. Tasks run in submission order; the first failure is rethrown after all already-started tasks have settled.

writeCodeWorkspaceFile(Directory ticketDir, List<String> repoPaths) → void

Writes the VS Code .code-workspace file for ticketDir with one folder entry per repository in repoPaths (deduplicated, insertion order kept).

writeTicketJson(Directory ticketDir, TicketJson ticket) → void

Writes (overwriting) ticket to <ticketDir>/ticket.json.

Typedefs

BranchSelector = Future<String?> Function(List<String> branches)

Lets the user pick one branch from branches; returns null on cancel.

CopyDirectory = Future<void> Function(Directory src, Directory dest)

Copies a directory tree; injectable for tests.

DirectoryFactory = Directory Function(String path)

Typedef for creating Directory instances (for testing).

EditMessage = Future<String?> Function(String initialMessage)

Typedef for editing a commit or merge message interactively.

FetchRepoUrl = Future<String?> Function(String packageName)

Resolves the repository URL of a hosted dependency. Subset of fetchDependencyRepoUrl without named args, for test stubs.

ProcessStarter = Future<void> Function(String executable, List<String> arguments, {bool runInShell})

Typedef for launching a process, mainly for testability.

ReadLineFromStdIn = String? Function()

Typedef for reading one line from stdin (for injection & tests).

ReadManifestVersion = Future<String?> Function(Directory repoDir)

Reads the version repoDir currently declares in its manifest, or null when it declares none.

RunDna = Future<void> Function(List<String> args)

Runs one gg dna command — init, add or build — with args. The seam that lets the tests skip the package managers and the network.

SelectOrganization = Future<Organization?> Function(String repoName, List<Organization> organizations)

Lets the user pick the organization a repository named repoName should be taken from. Returns null when the selection was cancelled.

TicketJsonFetcher = Future<String> Function(Uri url)

Downloads the ticket.json at url; injectable for tests.

Exceptions / Errors

MergeConflictException

Thrown when merging the default branch into a feature branch ends in conflicts.

RepoFreshnessException

Thrown when repositories could not be brought to their remote state.