ship-it

Ship: Branch, Commit, Push & PR

Arguments

Optional text used as the commit message subject, branch name prefix, and PR title (e.g. fix login timeout).

Special argument keywords (checked before treating $ARGUMENTS as a title):

• help, --help, -h, ? → skip the workflow and read references/options.md
• draft or --draft → create a draft PR (equivalent to the Draft PR option). If additional text follows (e.g. draft fix login timeout), use the remainder as the title/branch prefix.

If the user's message contains "draft" (e.g. "create a draft pr", "ship it as draft"), treat it the same way — enable draft mode and derive the title from any remaining description.

Process

1. Preflight Checks

git status
git ls-files --others --exclude-standard   # untracked files not shown by diff
git branch --show-current
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
# Fallback if origin/HEAD is unset
if [ -z "$DEFAULT_BRANCH" ]; then
  DEFAULT_BRANCH=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | sed 's/.*: //')
fi
git diff --stat
git diff --stat --cached
gh auth status

Determine:

• What is the default branch? (detect from remote ref, do not assume main)
• Are there changes to commit? Include both modified tracked files (git diff) and untracked files (git ls-files --others). If nothing at all, abort with message.
• Are we on the default branch? (If so, need to create a branch)
• Are we already on a feature branch?
• Is gh CLI installed and authenticated? (If not, abort: "Install and authenticate the GitHub CLI: https://cli.github.com")
• Are we in detached HEAD state? (If so, create a branch before proceeding)

2. Create Branch (if needed)

Skip this step if already on a feature branch — use the current branch.

If on the default branch or in detached HEAD, create and switch to a new branch:

# Check if the desired branch name already exists on the remote
git ls-remote --heads origin <branch-name>
# If output is non-empty, append a suffix: <branch-name>-2
git checkout -b <branch-name>