/gitx

GitX

Default action

On a bare invocation—$gitx, gitx, or a skill-UI invocation with no extra command—immediately execute the Smart commit workflow. Make the first action a repository inspection with Git status and the relevant diff. After inspecting, create the appropriate commit or report that there is nothing to commit.

Treat a bare invocation as an action, never as a help request. Do not announce that GitX was loaded, list commands or examples, ask which command to run, or wait for more instructions. Show the command list only when the user explicitly asks for help or available commands.

Commands and dispatch

Match natural-language requests to the commands below. Route “check my changes” or “show git status” to Status when the user wants a read-only summary; route “run tests before committing” to Checks. Use Doctor for Git workflow diagnosis and Plan for a commit preview. Read supporting references only when their workflow or loading condition applies.

Route gitx issue by argument shape, not by the intent implied by its wording. An argument containing only an issue number, such as 123 or #123, selects the existing-issue implementation workflow. Treat every other non-empty argument as a description for a new GitHub issue, even when it contains words such as “fix,” “update,” or “resolve.” With no argument, ask for the issue description. Never implement a problem supplied as a non-numeric gitx issue description.

For gitx ship [base], the optional argument is the PR's destination branch, never the name of a new feature branch. For example, gitx ship dev targets dev. Dispatch to Ship, not directly to Branch or Pull requests.

Project preferences and setup

Before applying defaults for commits, planning, branches, checks, PRs, or ship, look for .gitx.json at the current working-tree root (git rev-parse --show-toplevel). If present, read Project preferences, validate it, and apply only fields relevant to the requested workflow. If absent, preserve the existing behavior. Never create configuration during an ordinary command or execute configured checks merely because the file exists.

Explicit user choices override saved preferences; saved preferences override GitX's inferred defaults. Required repository instructions and execution permissions still apply. Invalid configuration must be explained before a dependent mutation; read-only commands may report it without stopping unrelated inspection.

For gitx setup, follow the reference to inspect local conventions, preview the exact proposed JSON, and create or update only the root .gitx.json. Setup does not run checks, stage, commit, push, create a PR, or require GitHub authentication.

Smart commit

1. Inspect git status and both staged and unstaged diffs. Prefer staged changes; otherwise use all safe changed files. For gitx files <paths>, apply this preference within only those paths. A partially staged file contributes only its staged edits when staged changes are selected. Preserve excluded staged changes and all unselected working-tree edits.

2. Include modified tracked files, safe untracked files, and deletions. Exclude ignored files and warn before including risky files.

3. Group the selected changes by purpose, including individual edits within the same file. Read Same-file commit splitting when a file contributes to multiple groups or staging must be isolated from unselected edits. Keep overlapping or dependent edits together unless a coherent sequence of intermediate versions exists; order prerequisites first.

4. If one commit is appropriate, create one clear Conventional Commit. For gitx type <type> or gitx scope <scope>, use the supplied type or scope. When inferring a scope, use configured commitScopes if present; omit the scope when none fits rather than inventing one. Apply this to every proposed group, including gitx plan.

5. If two or more commits are appropriate, calculate the real number of logical groups and ask:

   Do you want me to create N commits or one commit?

   Before asking, show each proposed message and the edits belonging to it, identifying functions or hunks when a file appears in multiple groups. Replace N with the real number. Never show N or {count} literally. Create multiple commits only if the user chooses multiple commits; otherwise create one commit. Execute the approved groups with index-only patches as described in the reference; do not stage a whole file containing unselected or deferred edits.

6. For gitx body, add a useful body to each commit message.

7. Do not push as part of a smart commit. Push only for gitx push or when the user explicitly asks to push.

Commit planning

For gitx plan, use Smart commit's selection and grouping rules and show the proposed commit group count, files and edit summaries per group, and proposed Conventional Commit messages. Identify shared files, dependencies, and edits that must stay together. Do not change files or the index, create Git objects, commits, branches, or pushes; the reference's execution steps apply only to committing.

Branch

For gitx branch [name]:

1. Keep existing changes; do not discard or stash them unless the user explicitly asks.
2. Use a valid supplied branch name exactly. If no name is supplied, derive a lowercase kebab-case name and apply configured branchPrefix when present: use a string as the fixed prefix, or choose the best-fitting prefix from an array according to Project preferences. Otherwise infer an appropriate prefix from the intended work: feat/ for new functionality, fix/ for bug fixes, hotfix/ only for urgent production fixes, docs/ for documentation, refactor/ for restructuring, test/ for tests, or chore/ for maintenance. If the prefix is unclear, ask the user; never default to hotfix/.
3. Check whether the branch exists locally or on origin. If it does, ask whether to switch to it or choose another name. Never overwrite it.
4. Create and switch with git switch -c <branch-name>.
5. Do not commit or push unless the command is gitx branch check or the user explicitly asks.

For gitx branch check, create a branch using the naming rules above, then follow the Checks behavior and Smart commit behavior.

Checks

For gitx check, use configured checks in order when present; otherwise detect relevant checks such as npm test, npm run lint, pnpm test, pytest, cargo test, go test ./..., or make test. Follow the preferences reference's command inspection and working-directory rules. Include checks required by repository instructions even if absent from the configured list. If checks fail, ask whether to commit anyway. Ship retains its stricter stop-on-failure behavior.

When splitting commits, run requested checks against each proposed staged snapshot in isolation, following the reference. A passing check on the complete working tree does not validate intermediate commits. Ordinary smart commits require diff and dependency inspection but do not implicitly request running the test suite. Report which snapshots were tested and any checks that could not run.

Pull

For gitx pull:

1. Inspect the current branch, upstream, and working tree. Do not pull with uncommitted changes that could be overwritten; explain the state and ask the user how to proceed.
2. Check that a remote named origin exists. If it does not, say that nothing was pulled; do not select another remote automatically.
3. Pull the current branch from origin, using the repository's existing pull/rebase configuration. If origin has no branch with that name, explain that there is nothing to pull. Do not use --force or discard local work.
4. If integration creates conflicts, stop the pull workflow and follow the Conflict resolution behavior.

Push

For gitx push:

1. Check that a remote named origin exists. If it does not, say that nothing was pushed; do not select another remote automatically.
2. Push the current branch to origin. If it has no upstream, create one immediately with git push -u origin <branch>.

Pull requests

For gitx pr [base], read Pull requests for base resolution, publication, existing-PR handling, and creation. That reference also owns the title, body, and readiness conventions shared with Ship.

Ship

For gitx ship [base], read Ship workflow. The command authorizes creating a feature branch when needed, running checks, committing selected changes, pushing the source branch to origin, and creating or updating an open PR through that push. It does not authorize merging the PR, force-pushing, or automatic integration of diverged history.

Reuse Branch naming, Smart commit selection and grouping, Checks detection, and project preferences. Read the shared PR conventions when preparing a PR. Ship's reference owns publication sequencing, including check failures and pushing before returning an existing PR.

GitHub issues

For gitx issue, use the argument-shape dispatch above, then read the selected workflow in GitHub issues. The reference defines prerequisites, implementation boundaries, and the new-issue template.

Conflict resolution

For gitx resolve or an in-progress merge or rebase conflict:

1. Inspect the operation state, history, and every conflicting file.
2. Trace both sides of each conflict to their source commits and understand each change's intent. Read commit messages and locally available issue or PR context when present.
3. Resolve every hunk by preserving both intents where compatible. If they conflict, choose the behavior that best fits the integration goal and clearly note the trade-off. Do not invent unrelated behavior or abort the operation unless the user explicitly asks.
4. Run the project's relevant checks, using configured checks in their listed order when present and including repository-required checks; otherwise normally run typecheck, tests, then formatting. Fix problems introduced by the resolution.
5. Stage the resolved files and finish the operation: commit the merge, or run git rebase --continue and repeat until the rebase completes. Do not force-push.

Status and history

For gitx status, show the current branch, staged files, unstaged files, untracked files, and a concise changed-file summary. Do not modify the repository.

For gitx tree, show the current branch and upstream, a working-tree summary, ahead/behind counts against the upstream or origin, the current PR when available, and a compact graph of the most recent 20 commits. Do not fetch, pull, push, create branches, or otherwise modify the repository.

Repository diagnosis

For gitx doctor [problem], read Repository diagnosis. Inspect local repository state and any error supplied by the user, explain observed blockers and their practical consequences, and recommend the smallest appropriate next step. An optional problem description focuses the diagnosis; it is not authorization to repair anything. Without one, inspect common workflow blockers.

Keep diagnosis read-only: do not fetch, change files or Git state, run project checks or hooks, test a push, start authentication, or apply repairs. Distinguish confirmed findings from possible causes and unavailable information. Local remote-tracking refs may be stale, and a failed Git operation cannot always be explained from local state. Do not route a doctor request into Smart commit or Conflict resolution merely because changes or conflicts are present.

Secret scanning

For gitx scan, read Secret scanning for read-only scan scope, tool selection, exposure classification, redaction, and the report format and rating.

Amend

For gitx amend, first ask for confirmation and show the proposed amended commit message. Only after the user confirms, amend the most recent commit. Do not amend a merge commit. Do not force-push; if the amended commit was already pushed, explain that a normal push will be rejected and ask the user how they want to proceed.

Safety and risky files

Always warn before including likely secrets, credentials, private keys, logs, or build artifacts, including .env, *.pem, *.key, credentials, token, secret, api_key, *.log, dist/, build/, and node_modules/.