GitOne error codes

Every GitOne failure prints its code as the first token of the message. Each one below states what it means, what usually causes it and what to do next. Nothing here is a warning - a code means the operation stopped and your repositories were not changed.

Configuration

CONFIG001

configuration missing

Usually: Neither this directory nor any parent contains a .gitone.yml, so there is no GitOne project here. A project is always the nearest directory above you that has one.
Do this: Run gitone setup to create a project, or change into a directory inside an existing one.

CONFIG002

invalid YAML

Usually: The file parses as broken YAML, contains duplicate keys, holds several YAML documents, or has a field GitOne does not know. Unknown fields are errors on purpose - a typo must not be silently ignored.
Do this: The message names the line. Fix it and run gitone repo validate until it passes.

CONFIG003

invalid configuration

Usually: The YAML is well-formed but the configuration is not usable: a duplicate ownership pattern, an unsupported pattern such as src/[ab].md or docs/**/**/*.md, a repository name outside [a-z][a-z0-9_-]*, the reserved name all, a version other than 1, a repository with no paths, remote and remotes.origin disagreeing, or a default_branch or remotes key that native Git itself refuses.
Do this: The message names the exact conflict. Patterns are exact paths like README.md, * inside one path segment and at most one ** segment, as in src/**, docs/**/*.md or **/*.md. default_branch and every remote name are checked with git check-ref-format before anything is created, so bad branch, -dash and feature.lock are rejected here rather than during gitone init.

Paths and ownership

PATH001

path is not assigned to any repository

Usually: A relevant file matches no ownership pattern in any repository. This is the most common GitOne error and it is the tool doing its job: it does not know where the file belongs, so it stops.
Do this: Add the path to the paths of exactly one repository - .gitone.yml for public, .gitone.local.yml for private - or add it to .gitignore if it should not be tracked at all.

PATH002

path is assigned to more than one repository

Usually: A file matches ownership patterns in two repositories at once. There is no priority rule and no most-specific-match rule, so GitOne refuses instead of picking one. Non-identical patterns may overlap in the configuration; the conflict appears when a concrete path matches both.
Do this: Adjust or remove one of the reported ownership patterns so the path matches exactly one repository, then rerun the command.

PATH003

path is otherwise unsafe

Usually: A path is protected by rules.protected_paths, or it is something GitOne will not manage: a nested or bare Git repository, a non-regular file, a name containing ASCII control characters, a case-insensitive collision with another path, or one of the reserved paths .gitone/ and .gitone.local.yml reaching an index or a commit. A symbolic link also lands here unless it is a safe internal alias like .claude/skills -> ../.agents/skills: a relative target that resolves inside the project, exists as a regular file or a real directory, is reached without passing through another link, and belongs to the same repository as the link. Absolute, escaping, dangling, empty, cross-repository, chained and cyclic links are refused, as is any link that is or reaches .gitone.yml, .gitone.local.yml, .gitignore, .gitone/, .git/ or a protected path.
Do this: The message states which of these it is, and for a link it names the link, its stored target and the concrete reason. A protected path is a hard deny that ownership never overrides - move the file or remove the protection deliberately. A link and its target must be selected and changed together, so a partial add, unstage or restore is refused and nothing changes.

Repositories

REPO001

repository invalid or unavailable

Usually: The configuration is valid but the managed repositories are not usable: none is initialized yet, some are missing, the metadata below .gitone/repositories/ is not a GitOne repository, the repositories are on different branches, or a named target has no configured origin.
Do this: The message names the command that makes the project usable - gitone init on a fresh project, gitone migrate when a root .git/ exists, gitone switch when the branches disagree, and gitone doctor for anything else.

GIT001

native Git failure

Usually: The underlying git command failed and GitOne is reporting it rather than interpreting it. Authentication, a failing hook, a full disk, a missing object, an unreadable configuration.
Do this: The message contains the exact git invocation and its output. Run that command yourself to see the full picture.

BRANCH001

branch listing or creation refused or failed

Usually: The name breaks native Git branch-name rules, a repository has no commit on its current branch, a repository is not on a branch, the repositories are on different branches, or one already has the branch.
Do this: Every problem is reported at once and nothing was changed. Commit first if a repository is unborn; use gitone switch to put all repositories on the same branch.

SWITCH001

switch refused or failed

Usually: A repository does not have the branch, is not on a branch, has staged or unstaged changes, the target tree contains a path the repository does not own, or the checkout would overwrite an existing working-tree file.
Do this: Commit or undo your changes first - GitOne never stashes, discards or merges to make a switch possible. Create a missing branch with gitone branch .

Remote operations

PUSH001

push preflight failed

Usually: One of the checks before the first remote is touched failed: a push: disabled repository was named explicitly, require_clean_worktree is set and the tree is dirty, origin is missing or has different fetch and push URLs, the remote is unreachable, the push would not be a fast-forward, an outgoing commit or the resulting tree contains a path the repository does not own - or there is no terminal to confirm on and --yes was not passed.
Do this: Nothing was pushed. For the non-interactive case add --yes. For a non-fast-forward, fetch and reconcile the branch yourself before retrying.

FETCH001

fetch failed for one or more repositories

Usually: A remote could not be contacted or refused the ref listing - authentication, transport, an unreachable host.
Do this: A fetch across repositories is not atomic. The report above the error names which repositories already updated their remote-tracking refs; rerun gitone fetch to retry the rest.

PULL001

pull refused or failed

Usually: A repository that would move has staged or unstaged changes, its branch does not track exactly origin/, the remote-tracking branch is missing after the fetch, the branch has diverged so no fast-forward is possible, or the incoming tree contains a path the repository does not own.
Do this: A pull is fast-forward only and no flag changes that. Resolve a diverged branch with plain Git yourself, then return to gitone pull.

CLONE001

clone refused or failed

Usually: The destination already exists, the bootstrap repository has no committed .gitone.yml on its default branch, more than one or no repository owns that file, the owning repository’s configured origin is not exactly the URL you cloned, a configured origin lacks the default branch, or an incoming tree contains a path its repository does not own.
Do this: Nothing was created and no existing path was changed. Clone the URL the committed configuration names, and clone into a path that does not exist yet.

Locking, recovery and setup

LOCK001

another GitOne operation is currently running

Usually: Only one mutating operation runs at a time. The message names the process ID and the command holding the lock.
Do this: Wait for it to finish and retry. gitone doctor and gitone repo validate are read-only and work while the lock is held.

REC001

an interrupted operation must be recovered first

Usually: A previous add, unstage, restore, commit, branch, switch or pull was interrupted and left recorded state under .gitone/recovery/. GitOne refuses to start anything new on top of it.
Do this: Run gitone recover to finish it, or gitone abort to undo it. Never delete .gitone/recovery/ by hand. For an interrupted push, both commands only report what actually reached the remotes.

MIG001

migration refused, failed or interrupted

Usually: The project is not a plain root repository - a .git file rather than a directory, linked worktrees, submodules, a bare repository, a nested repository, an already migrated project - or a previous migration was interrupted. gitone backup also reports a missing, ambiguous, unknown, unsafe or invalid backup selection and every refused or failed restoration with this code.
Do this: For an interruption, gitone migrate offers to restore the verified backup instead of migrating again. For a backup command, run gitone backup list and pass the full ID as --backup ; a restore additionally needs the root .git path to be absent. The backup is always kept; it is never moved or consumed.

SETUP001

interactive setup refused

Usually: gitone setup asks questions, so it needs an interactive terminal on standard input. It also refuses inside another GitOne project or another Git repository, on an invalid existing configuration, on an interrupted migration, or on repository state under .gitone/ that neither init nor migrate explains.
Do this: Run it in a real terminal. To set a project up non-interactively, write .gitone.yml yourself and run gitone init or gitone migrate.

AGENT001

AGENTS.md missing, not current or not safely editable

Usually: gitone agents found no AGENTS.md, one without the GitOne instructions, or a marked block that is no longer the current text. gitone agents update reports it too when the file is one GitOne must not edit by itself: a symbolic link or another non-regular file, recognizable GitOne text that is neither marked nor exactly the current block, duplicate blocks, marked and unmarked instructions together, or missing and repeated markers.
Do this: Run gitone agents update for a missing, incomplete or outdated block. For an unclear file, edit it by hand until it holds exactly one block between and , then run gitone agents again.

Command line

CLI001

unsupported command or flag

Usually: GitOne runs an allowlist and forwards nothing to git. reset, tag, merge, rebase, stash, Git pathspecs, globs, -- separators and most Git flags are rejected here - as are -h, gitone help, and any argument after --help. Bare gitone and a command group called without a subcommand are not refusals: they print their help and exit 0.
Do this: Every refusal is followed by one hint line naming the page that lists the accepted form - gitone --help when the input names a known command, gitone --help otherwise. Do not work around it by falling back to plain git: that bypasses every ownership check.

SHOW001

requested path absent from HEAD or index

Usually: The request was valid but the named path does not exist in the selected source. This exits 2, not 1, so an editor integration can tell an absent version from a broken command.
Do this: Usually nothing is wrong: a file that is untracked has no HEAD version, and a file that is not staged has no index version.

VSCODE001

VS Code CLI or extension installation failed

Usually: The code command is not on PATH, the named VSIX does not exist, the extension is already installed and --force was not passed, or VS Code’s own CLI reported a failure.
Do this: Install a downloaded VSIX with gitone vscode install --vsix . A completed project setup stays in place - only the optional extension step failed.

Every failure prints its code as the first token of the message. For the complete behavior of each command, read the usage guide.