yf-push

Promote the current git branch to staging and/or main, worktree-aware.

Pushes the feature branch, merges it into staging and optionally main (--no-edit), and pushes those branches. If staging or main is already checked out in another git worktree, commands run there (git -C). Otherwise this worktree is switched and restored when the run ends.

Does not run your test suite. YourFam does not need an API key (unlike yf-commit).

• Source / README: https://github.com/YourFam/yf-push
• npm: https://www.npmjs.com/package/@yourfam/yf-push
• Unscoped alias: https://www.npmjs.com/package/yf-push
• Issues: https://github.com/YourFam/yf-push/issues

Install

Node 20+.

npm install -g @yourfam/yf-push

Then from any git repo:

yf-push --s

The command is yf-push.

Alternate modes of install

-g = on your machine (global).
-D = in this project (devDependency).

| | npm install -g @yourfam/yf-push | npm install -D @yourfam/yf-push | |---|---|---| | Where it goes | Global npm prefix (your user/system) | node_modules/ + package.json of the current repo | | Command | yf-push from any folder | npx yf-push (or a script) in that repo | | Other repos | Works | Not installed there | | Git | Not committed | Listed in package.json; teammates get it with npm install | | Typical use | A CLI you want everywhere | A tool this project uses in scripts/CI |

For yf-push as a daily command, use -g. Use -D only if this one repo should own the tool.

With -D, the binary lives in that repo’s node_modules/.bin/. Your shell PATH does not include that, so plain yf-push will not work. From that repo:

npx yf-push --s

No install at all (npm fetches and runs the published package):

npx @yourfam/yf-push --s
npx yf-push --s

npx yf-push is the unscoped alias of @yourfam/yf-push (same CLI, same version). Both are yours.

Usage

A destination flag is required. Bare yf-push aborts and does not run git.

yf-push --s                 # feature → staging
yf-push --staging           # same
yf-push --m                 # feature → staging, then staging → main
                            # (if staging does not exist at all: feature → main)
yf-push --main              # same
yf-push --s --m             # same as --m
yf-push --m --skip-s        # feature → main; do not touch staging
yf-push --m --skip-staging  # same
yf-push -y --s              # skip confirm
yf-push --yes --m
yf-push --auto --m --skip-s
yf-push --help
yf-push --version

Short flags that take a single hyphen: only -y, -h, -V.
-s, -m, -staging, -skip-s, -auto are unknown; use the two-dash form.

Positionals are illegal, including a branch name: yf-push --s my-feature is an error. The current branch is always HEAD in the current directory.

Default remote: origin. Default branches: staging, main.

Confirm

Without -y / --yes / --auto, each destination stage prints a plan and waits. Enter / y proceeds. n / Ctrl+C cancels. Non-interactive stdin without -y exits 1 (does not hang).

--m asks twice: staging first, then main (only after staging succeeded). After staging lands, checkmarks print before the main prompt. Cancel on the main prompt does not undo origin/staging.

If --m is used without --s / --staging, and there is no origin/staging and no local staging branch, yf-push skips staging and merges the feature into main (same git steps as --m --skip-s, without the diverge warning). Explicit --s still requires staging.

-y / --yes / --auto skips the plan and the Enter / y prompt. Each stage prints one Auto-approved line, then the same checkmarks as work completes.

A feature branch that is already on origin is reported as already on origin, not as a new push. Merge and push are separate lines; a merge in another worktree names that path.

--m --skip-s is a hotfix path: it warns that main and staging can diverge (interactive only; -y still notes staging skipped on the auto-approved line).

Worktrees

git worktree list always includes the current checkout.

For each target (staging, then main if needed):

• If that branch is already checked out in another worktree, git runs there. This worktree’s HEAD does not change.
• If it is not checked out elsewhere, this worktree checks it out, then restores the original branch (success, failure, SIGINT/SIGTERM).

The tool never force-pushes. It aborts if the working tree is dirty (untracked files count as dirty), if you are on staging / main / a detached HEAD, if a target worktree is locked / detached / mid-rebase / merge / bisect / cherry-pick, if a required origin/staging or origin/main is missing after fetch, or if the local target is ahead of origin (those commits are not pushed). --m without --s does not require origin/staging when local staging is also absent.

A staging push followed by a main failure is partial success: staging is not rolled back.

Publish the unscoped alias (maintainers)

The GitHub repo publishes two npm packages at the same version:

1. npm publish --access public from the repo root → @yourfam/yf-push
2. Then from alias/, with matching version and dependencies["@yourfam/yf-push"]:

cd alias
npm publish --access public

That second package is named yf-push and only shims the scoped CLI so npx yf-push cannot be squatted.