Files
Willie dd6991ca3c fix(push): refuse unpushed config.yaml history at root scope (#366) (#372)
* fix(push): reject unpushed config history at root scope

Untracking config.yaml at the tip still uploads its contents from earlier local commits. Refuse root-scope pushes before mutation and before upload when unpublished history adds or changes the file or its directory tree, without rewriting history.

Share the check across the CLI and dashboard, return unpushed_config_history, and allow removals and config inherited unchanged from upstream merges. Cover first pushes, dry runs, push --pull, directory paths, renames, and merge commits, and document manual repair in all website locales.

Fixes #366

* fix(push): check exactly what push sends for config history

Review of the config history guard found two range problems:

- The guard checked @{u}..HEAD, but a same-named upstream was pushed with
  a bare `git push`. With remote.pushDefault or push.default=matching that
  could send config-bearing commits to another remote, or other branches,
  that the guard never looked at. PushArgs now always names the upstream
  remote and branch (read from branch config, so names with "/" survive),
  so the checked range and the pushed range are the same.
- Without an upstream every commit on HEAD counted as unpushed, so a
  config.yaml already published on origin followed by the
  "Keep config.yaml out of version control" commit was refused. The guard
  now checks HEAD --not --remotes=<push remote>.

The refusal message now suggests rebasing from just before the oldest
offending commit instead of @{u} or --root, which would rewrite commits
the remote already has.

* fix(push): check config history against the remote's live refs

Local remote-tracking refs can be stale. When another machine force-pushes
the remote to drop a leaked config.yaml commit, this clone's
refs/remotes/<remote>/... still contains it, so the guard treated the leak
as already published and HEAD:main, still a fast-forward, would publish it
again.

The guard now excludes only the objects the push remote's refs point to
right now (git ls-remote), limited to objects this clone has. It falls back
to local remote-tracking refs only when the remote cannot be reached, in
which case the push fails anyway. Revisions go to git log on stdin as
"^<id>" lines because git before 2.42 rejects "--not" there.

* fix(push): screen config history against every push URL, without replace refs

Two more ways the screened history could differ from what git push uploads:

- `git ls-remote <remote>` queries the fetch URL, but git push sends to every
  remote.<name>.pushurl. A commit already on the fetch URL could still be
  new to a push URL. The guard now lists `git remote get-url --push --all`
  and excludes only objects that every push URL has.
- With a refs/replace/* entry for an offending commit, git log read the
  sanitized replacement while the push pack carries the original. The log
  and the rebase-base lookup now run with --no-replace-objects.

* fix(push): let pushes the remote will reject reach the pull step

Our own review of the config history guard found two problems:

- When another machine had pushed, the remote's tip was unknown locally, so
  no live ref survived the "objects this clone has" filter and the whole
  history counted as unpushed. A config.yaml published long ago, followed by
  the stop-tracking commit, then blocked `push --pull` before it could pull,
  and replaced the plain push's ErrPushRejected hint. A push URL whose
  destination branch tip this clone lacks rejects the push as
  non-fast-forward and receives nothing, so it is now left out, and the
  check passes when every push URL is like that. `push --pull` re-runs the
  check after pulling, with the tip known.
- PushRemote read branch.<b>.remote even when @{u} no longer resolved, while
  PushArgs then pushed to origin. pushTarget now follows the same
  HasUpstream rule as PushArgs.
2026-10-04 03:09:17 +08:00

146 lines
5.8 KiB
Markdown

---
sidebar_position: 1
---
# push
Commit and push source to git remote.
Use [`commit`](./commit.md) instead when you only want a local checkpoint without pushing.
```bash
skillshare push # Auto-generated message
skillshare push -m "Add pdf" # Custom message
skillshare push --pull # Merge remote changes, push, then sync
skillshare push --dry-run # Preview
```
## When to Use
- Share skill changes with your other machines via git
- Back up your skills to a remote repository
- After editing skills, commit and push in one command
If you want to save a local checkpoint without sharing it yet, use [`skillshare commit`](./commit.md).
## What Happens
```mermaid
flowchart TD
CMD["skillshare push"]
CHECK["1. Check repository status"]
STAGE["2. Stage all changes"]
COMMIT["3. Commit"]
PUSH["4. Push to remote"]
CMD --> CHECK --> STAGE --> COMMIT --> PUSH
```
## Options
| Flag | Description |
|------|-------------|
| `-m, --message <msg>` | Commit message (default: "Update skills") |
| `--pull` | Merge remote changes before pushing, then sync targets (see [Push and Pull Together](#push-and-pull-together)) |
| `--dry-run, -n` | Preview without making changes |
## Git Root Scope
`push` operates on the directory selected by the `git_root` config field (default: `skills` source). See [commit — Git Root Scope](./commit.md#git-root-scope) for the scope table. If `git_root` was changed but the git repo still lives in another scope's directory, `push` prints a "Git root mismatch" error with the exact `git init` / `mv` commands to fix it. See [Changing the scope after init](/docs/reference/targets/configuration#git-root).
At `git_root: root`, `push` refuses if any unpushed commit adds or modifies `config.yaml` or a file under `config.yaml/`, even if a later commit removes it. This also applies to `--pull` and `--dry-run`; the check runs before staging or pulling, and dry-run changes nothing. The error lists the affected commit hashes. A commit counts as unpushed when the remote that `push` targets (the upstream remote, or `origin` before the first push) has no ref containing it, so history that remote already has is never refused. `push` always sends only the current branch to that remote, regardless of `push.default` or `remote.pushDefault`.
Remove the file from the listed commits before retrying: run the `git rebase -i <commit>` shown in the error (it starts just before the oldest affected commit), mark the affected commits for editing, then run `git rm -r --cached -- config.yaml`, `git commit --amend`, and `git rebase --continue` at each edit. Skillshare never rewrites history automatically. A commit that only stops tracking a previously published `config.yaml` can still be pushed; adding a removal commit after an unpushed addition does not remove that earlier content from history.
## Prerequisites
Your source directory must be a git repository with a remote:
```bash
# Set up during init (recommended):
skillshare init --remote git@github.com:you/my-skills.git
# Or add remote to existing setup:
skillshare init --remote git@github.com:you/my-skills.git
```
Init automatically creates the initial commit, so `push` works immediately after setup.
## First Push Upstream Mapping
On first push (no upstream tracking yet), `skillshare push` auto-configures upstream:
- If remote already has a default branch (for example `main` or `trunk`), local changes are pushed to that remote default branch.
- If remote is empty, it pushes to your current local branch.
This avoids accidentally creating the wrong remote branch (for example local `master` while remote uses `main`).
## Examples
```bash
# Quick push with auto message
skillshare push
# Custom commit message
skillshare push -m "Add commit-commands skill"
# Preview what would be pushed
skillshare push --dry-run
```
## Conflict Handling
If the remote has newer commits:
```bash
$ skillshare push
✗ Push failed
Remote may have newer changes
Next
skillshare pull get them first
skillshare push then push again
```
Solution:
```bash
skillshare pull # Merge remote changes with yours
skillshare push # Push your changes
```
`pull` merges the remote commits with the ones you have not pushed yet, so the second `push` goes through. See [When Both Machines Committed](/docs/reference/commands/pull#when-both-machines-committed) for what happens if both sides changed the same file.
## Push and Pull Together
`skillshare push --pull` does the whole round trip in one command:
1. Commits your local changes (if any)
2. Merges the remote's new commits, the same way [`pull`](/docs/reference/commands/pull) does
3. Pushes the result
4. Syncs targets for what the git root scope holds, like `pull`
If the merge hits a conflict, nothing is pushed and targets are not synced. Your changes stay committed locally; resolve the conflict, then run `skillshare push --pull` again. If the push succeeds but syncing targets fails, the remote is already updated, so run the `skillshare sync ... --global` command it prints to retry (one per synced resource, matching your `git_root`).
At `git_root: root`, if the merge brings in a `config.yaml` that the remote tracks, `push --pull` keeps this machine's copy and removes `config.yaml` from the remote in the same push.
`--pull` never rebases and never force-pushes.
## Workflow
Typical workflow for sharing skills:
```bash
# 1. Make changes to skills
# 2. Push to remote
skillshare push -m "Update my-skill"
# On another machine:
skillshare pull # Gets changes and syncs
```
## See Also
- [commit](/docs/reference/commands/commit) — Commit locally without pushing
- [pull](/docs/reference/commands/pull) — Pull from remote
- [sync](/docs/reference/commands/sync) — Sync to local targets
- [Cross-Machine Sync](/docs/how-to/sharing/cross-machine-sync) — Full setup