gitwise-cli 0.35.0__tar.gz → 0.36.0__tar.gz

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/CHANGELOG.md

@@ -3,6 +3,18 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.36.0 (2026-07-22)
+
+### Fix
+
+- remove unimplemented clean refs contract
+
+## v0.35.1 (2026-07-22)
+
+### Fix
+
+- **snapshot**: honor canonical agents layout
+
 ## v0.35.0 (2026-07-22)
 
 ### Feat

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitwise-cli
-Version: 0.35.0
+Version: 0.36.0
 Summary: Python CLI for optimizing git workflows and Claude Code integration
 Project-URL: Homepage, https://github.com/drzioner/gitwise
 Project-URL: Repository, https://github.com/drzioner/gitwise

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/gitwise/__init__.py

@@ -1,6 +1,6 @@
 """gitwise -- CLI for optimizing git workflows and coding-agent integration."""
 
-__version__ = "0.35.0"
+__version__ = "0.36.0"
 
 
 def get_version() -> str:

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/gitwise/_cli_dispatch.py

@@ -125,7 +125,6 @@ def _run_clean(args: argparse.Namespace) -> int:
 
     return run_clean(
         branches=args.branches,
-        refs=args.refs,
         dry_run=args.dry_run,
         yes=args.yes,
         as_json=args.json,

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/gitwise/_cli_parser.py

@@ -157,16 +157,15 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--diff", action="store_true")
     p.add_argument("--max-commits", type=int, default=10, dest="max_commits")
 
-    p = sub.add_parser("snapshot", help="generate .claude/git-snapshot.md", parents=[parent])
+    p = sub.add_parser("snapshot", help="generate agent git snapshot", parents=[parent])
 
     p = sub.add_parser(
         "clean",
-        help="clean up stale branches and refs",
+        help="clean up stale branches",
         aliases=["branch-clean"],
         parents=[parent],
     )
     p.add_argument("--branches", action="store_true")
-    p.add_argument("--refs", action="store_true")
     p.add_argument("--dry-run", action="store_true")
     p.add_argument("--yes", "-y", action="store_true")
 

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/gitwise/_i18n_data.json

@@ -151,13 +151,9 @@
     "es": "gitwise clean --branches --dry-run",
     "en": "gitwise clean --branches --dry-run"
   },
-  "clean_refs_not_implemented": {
-    "es": "'clean --refs' no está implementado",
-    "en": "'clean --refs' is not implemented"
-  },
   "clean_specify_flag": {
-    "es": "especifica --branches  (o --refs)",
-    "en": "specify --branches  (or --refs)"
+    "es": "especifica --branches",
+    "en": "specify --branches"
   },
   "clean_to_delete": {
     "es": "para eliminar: gitwise clean --branches --yes",
@@ -2071,6 +2067,10 @@
     "es": "ejecutaría: git pull --ff-only en {dir}",
     "en": "would run: git pull --ff-only in {dir}"
   },
+  "update_deprecation_hint": {
+    "es": "update esta deprecado; usa `brew upgrade gitwise` para Homebrew o `uv tool upgrade gitwise-cli` para instalaciones con uv tool",
+    "en": "update is deprecated; use `brew upgrade gitwise` for Homebrew or `uv tool upgrade gitwise-cli` for uv tool installations"
+  },
   "updated_git_conventions": {
     "es": "actualizado: {file} (convenciones git agregadas)",
     "en": "updated: {file} (git conventions added)"

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/gitwise/clean.py

@@ -59,7 +59,6 @@ def _categorize(
 def run_clean(
     *,
     branches: bool = False,
-    refs: bool = False,
     dry_run: bool = False,
     yes: bool = False,
     as_json: bool = False,
@@ -70,11 +69,6 @@ def run_clean(
     user-cancelled), 1 on delete failures or missing flag, 2 when
     ``--json`` is used without ``--yes``.
     """
-    if refs:
-        return report_error(
-            "clean", as_json=as_json, msg=t("clean_refs_not_implemented"), code="not_implemented"
-        )
-
     if not branches:
         return report_error(
             "clean", as_json=as_json, msg=t("clean_specify_flag"), code="clean_specify_flag"

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/gitwise/snapshot.py

@@ -10,6 +10,13 @@ from gitwise.output import debug, print_header, print_json, status
 from gitwise.utils.json_envelope import ok_envelope
 
 
+def _snapshot_relative_path(root: Path) -> str:
+    """Return the snapshot path for the repository's active agent layout."""
+    if (root / ".agents").is_dir():
+        return ".agents/git-snapshot.md"
+    return ".claude/git-snapshot.md"
+
+
 def _append_branch_section(lines: list[str], *, root: Path) -> None:
     """Append the current branch section to *lines*."""
     branch = git_run(["branch", "--show-current"], cwd=root, check=False)
@@ -105,7 +112,7 @@ def run_snapshot(*, as_json: bool = False) -> int:
         return 1
 
     with status(t("status_snapshot_gen")):
-        path = generate_snapshot(root)
+        path = generate_snapshot(root, relative_path=_snapshot_relative_path(root))
 
     if as_json:
         print_json(ok_envelope("snapshot", path=str(path)))

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/gitwise/update.py

@@ -5,13 +5,16 @@ from pathlib import Path
 from gitwise.git import current_branch, has_upstream
 from gitwise.git import run as git_run
 from gitwise.i18n import t
-from gitwise.output import error, info, print_dim, print_header, print_json, status
+from gitwise.output import error, info, print_dim, print_header, print_json, status, warn
 from gitwise.utils.json_envelope import error_envelope, ok_envelope
 
 
 def run_update(*, dry_run: bool = False, as_json: bool = False) -> int:
     """Entry point for the ``gitwise update`` command. Pulls the gitwise repo via git."""
     install_dir = Path(__file__).parent.parent
+    upgrade_hint = t("update_deprecation_hint")
+    if not as_json:
+        warn(upgrade_hint)
     if not (install_dir / ".git").is_dir():
         if as_json:
             print_json(
@@ -19,6 +22,7 @@ def run_update(*, dry_run: bool = False, as_json: bool = False) -> int:
                     "update",
                     error=t("update_requires_git_clone"),
                     code="update_requires_git_clone",
+                    hint=upgrade_hint,
                 )
             )
         else:
@@ -26,7 +30,9 @@ def run_update(*, dry_run: bool = False, as_json: bool = False) -> int:
         return 1
     if dry_run:
         if as_json:
-            print_json(ok_envelope("update", dry_run=True, dir=str(install_dir)))
+            print_json(
+                ok_envelope("update", dry_run=True, dir=str(install_dir), hints=[upgrade_hint])
+            )
             return 0
         print_dim(t("update_dry_run", dir=str(install_dir)))
         return 0
@@ -35,7 +41,15 @@ def run_update(*, dry_run: bool = False, as_json: bool = False) -> int:
         msg = t("update_no_upstream", branch=branch)
         hint = t("update_no_upstream_hint", branch=branch)
         if as_json:
-            print_json(error_envelope("update", error=msg, code="no_upstream", hint=hint))
+            print_json(
+                error_envelope(
+                    "update",
+                    error=msg,
+                    code="no_upstream",
+                    hint=hint,
+                    hints=[upgrade_hint],
+                )
+            )
         else:
             error(msg, hint=hint)
         return 1
@@ -45,7 +59,9 @@ def run_update(*, dry_run: bool = False, as_json: bool = False) -> int:
         r = git_run(["pull", "--ff-only"], cwd=install_dir, check=False)
     if r.returncode == 0 and r.stdout.strip() and r.stdout.strip() != "Already up to date.":
         if as_json:
-            print_json(ok_envelope("update", updated=True, output=r.stdout.strip()))
+            print_json(
+                ok_envelope("update", updated=True, output=r.stdout.strip(), hints=[upgrade_hint])
+            )
             return 0
         for line in r.stdout.strip().splitlines():
             info(line)
@@ -53,13 +69,23 @@ def run_update(*, dry_run: bool = False, as_json: bool = False) -> int:
         if as_json:
             print_json(
                 error_envelope(
-                    "update", error=r.stderr.strip() or t("error_updating"), code="update_failed"
+                    "update",
+                    error=r.stderr.strip() or t("error_updating"),
+                    code="update_failed",
+                    hint=upgrade_hint,
                 )
             )
             return 1
         error(r.stderr.strip() or t("error_updating"))
         return 1
     elif as_json:
-        print_json(ok_envelope("update", updated=False, output=t("already_up_to_date")))
+        print_json(
+            ok_envelope(
+                "update",
+                updated=False,
+                output=t("already_up_to_date"),
+                hints=[upgrade_hint],
+            )
+        )
         return 0
     return 0

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gitwise-cli"
-version = "0.35.0"
+version = "0.36.0"
 description = "Python CLI for optimizing git workflows and Claude Code integration"
 readme = "README.md"
 license = "MIT"

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/share/claude/rules/gitwise.md

@@ -9,7 +9,7 @@ globs: "**/*"
 - Changed files: `gitwise diff` — never raw `git diff`
 - Status + log: `gitwise summarize` — never raw `git status` or `git log`
 - Branch switch: `gitwise worktree new <branch>` — never `git stash + checkout`
-- Snapshot: `gitwise snapshot` — regenerates `.claude/git-snapshot.md`
+- Snapshot: `gitwise snapshot`; writes `.agents/git-snapshot.md` when `.agents/` exists, otherwise `.claude/git-snapshot.md`
 
 ## Shell note
 

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/share/codex/agents/gitwise.toml.template

@@ -10,7 +10,7 @@ developer_instructions = """
 - Changed files: `gitwise diff` — never raw `git diff`
 - Status + log: `gitwise summarize` — never raw `git status` or `git log`
 - Branch switch: `gitwise worktree new <branch>` — never `git stash + checkout`
-- Snapshot: `gitwise snapshot` — regenerates `.claude/git-snapshot.md`
+- Snapshot: `gitwise snapshot`; writes `.agents/git-snapshot.md` when `.agents/` exists, otherwise `.claude/git-snapshot.md`
 
 ## Shell note
 

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/share/continue/rules/gitwise.md.template

@@ -8,7 +8,7 @@ description: Use gitwise CLI for git operations — gitwise diff, summarize, wor
 - Changed files: `gitwise diff` — never raw `git diff`
 - Status + log: `gitwise summarize` — never raw `git status` or `git log`
 - Branch switch: `gitwise worktree new <branch>` — never `git stash + checkout`
-- Snapshot: `gitwise snapshot` — regenerates `.claude/git-snapshot.md`
+- Snapshot: `gitwise snapshot`; writes `.agents/git-snapshot.md` when `.agents/` exists, otherwise `.claude/git-snapshot.md`
 - Audit: `gitwise audit --quick` — before large commits
 - Clean: `gitwise clean --branches` — remove stale branches
 - Optimize: `gitwise optimize` — gc, pack-refs, commit-graph

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/share/cursor/rules/gitwise.mdc.template

@@ -10,7 +10,7 @@ alwaysApply: true
 - Changed files: `gitwise diff` — never raw `git diff`
 - Status + log: `gitwise summarize` — never raw `git status` or `git log`
 - Branch switch: `gitwise worktree new <branch>` — never `git stash + checkout`
-- Snapshot: `gitwise snapshot` — regenerates `.claude/git-snapshot.md`
+- Snapshot: `gitwise snapshot`; writes `.agents/git-snapshot.md` when `.agents/` exists, otherwise `.claude/git-snapshot.md`
 - Audit: `gitwise audit --quick` — before large commits
 - Clean: `gitwise clean --branches` — remove stale branches
 - Optimize: `gitwise optimize` — gc, pack-refs, commit-graph

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/share/opencode/agents/gitwise.md.template

@@ -8,7 +8,7 @@ description: Use gitwise CLI for git operations — gitwise diff, summarize, wor
 - Changed files: `gitwise diff` — never raw `git diff`
 - Status + log: `gitwise summarize` — never raw `git status` or `git log`
 - Branch switch: `gitwise worktree new <branch>` — never `git stash + checkout`
-- Snapshot: `gitwise snapshot` — regenerates `.claude/git-snapshot.md`
+- Snapshot: `gitwise snapshot`; writes `.agents/git-snapshot.md` when `.agents/` exists, otherwise `.claude/git-snapshot.md`
 - Audit: `gitwise audit --quick` — before large commits
 - Clean: `gitwise clean --branches` — remove stale branches
 - Optimize: `gitwise optimize` — gc, pack-refs, commit-graph

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/share/pi/skills/gitwise.md.template

@@ -8,7 +8,7 @@ description: Use gitwise CLI for git operations — gitwise diff, summarize, wor
 - Changed files: `gitwise diff` — never raw `git diff`
 - Status + log: `gitwise summarize` — never raw `git status` or `git log`
 - Branch switch: `gitwise worktree new <branch>` — never `git stash + checkout`
-- Snapshot: `gitwise snapshot` — regenerates `.claude/git-snapshot.md`
+- Snapshot: `gitwise snapshot`; writes `.agents/git-snapshot.md` when `.agents/` exists, otherwise `.claude/git-snapshot.md`
 - Audit: `gitwise audit --quick` — before large commits
 - Clean: `gitwise clean --branches` — remove stale branches
 - Optimize: `gitwise optimize` — gc, pack-refs, commit-graph

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/share/schemas/v1/input/clean.json

@@ -36,10 +36,6 @@
       "type": "boolean",
       "default": false
     },
-    "refs": {
-      "type": "boolean",
-      "default": false
-    },
     "dry_run": {
       "type": "boolean",
       "default": false

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/tests/test_clean.py

@@ -8,6 +8,8 @@ import pytest
 from gitwise.clean import run_clean
 from gitwise.git import stale_branches
 
+from conftest import run_gitwise
+
 
 def test_dry_run_does_not_delete(
     monkeypatch: pytest.MonkeyPatch, tmp_git_repo_with_stale: Path
@@ -16,7 +18,7 @@ def test_dry_run_does_not_delete(
     before = stale_branches(tmp_git_repo_with_stale)
     assert len(before) == 3
 
-    rc = run_clean(branches=True, refs=False, dry_run=True, yes=True, as_json=False)
+    rc = run_clean(branches=True, dry_run=True, yes=True, as_json=False)
     assert rc == 0
 
     assert stale_branches(tmp_git_repo_with_stale) == before
@@ -28,7 +30,7 @@ def test_dry_run_lists_stale_branches(
     capsys: pytest.CaptureFixture,
 ) -> None:
     monkeypatch.chdir(tmp_git_repo_with_stale)
-    run_clean(branches=True, refs=False, dry_run=True, yes=True, as_json=False)
+    run_clean(branches=True, dry_run=True, yes=True, as_json=False)
     captured = capsys.readouterr()
     output = captured.out + captured.err
     for i in range(1, 4):
@@ -41,7 +43,7 @@ def test_apply_deletes_only_stale(
     monkeypatch.chdir(tmp_git_repo_with_stale)
     assert len(stale_branches(tmp_git_repo_with_stale)) == 3
 
-    rc = run_clean(branches=True, refs=False, dry_run=False, yes=True, as_json=False)
+    rc = run_clean(branches=True, dry_run=False, yes=True, as_json=False)
     assert rc == 0
 
     assert stale_branches(tmp_git_repo_with_stale) == []
@@ -157,7 +159,7 @@ def test_protected_branch_not_deleted(monkeypatch: pytest.MonkeyPatch, tmp_path:
 
     assert "develop" in stale_branches(local)
 
-    rc = run_clean(branches=True, refs=False, dry_run=False, yes=True, as_json=False)
+    rc = run_clean(branches=True, dry_run=False, yes=True, as_json=False)
     assert rc == 0
 
     r = subprocess.run(
@@ -174,7 +176,7 @@ def test_json_output_structure(
     """as_json=True outputs parseable JSON with deletable/skipped keys."""
     monkeypatch.chdir(tmp_git_repo_with_stale)
 
-    rc = run_clean(branches=True, refs=False, dry_run=True, yes=True, as_json=True)
+    rc = run_clean(branches=True, dry_run=True, yes=True, as_json=True)
     assert rc == 0
 
     captured = capsys.readouterr()
@@ -194,7 +196,7 @@ def test_clean_json_executes_delete(
     """Regression for Issue #45: --json without --dry-run must actually delete stale branches."""
     monkeypatch.chdir(tmp_git_repo_with_stale)
 
-    rc = run_clean(branches=True, refs=False, dry_run=False, yes=True, as_json=True)
+    rc = run_clean(branches=True, dry_run=False, yes=True, as_json=True)
     assert rc == 0
 
     data = json.loads(capsys.readouterr().out)
@@ -220,7 +222,7 @@ def test_clean_json_requires_yes(
 ) -> None:
     """Q1: clean --json without --yes must return yes_required envelope."""
     monkeypatch.chdir(tmp_git_repo_with_stale)
-    rc = run_clean(branches=True, refs=False, dry_run=False, yes=False, as_json=True)
+    rc = run_clean(branches=True, dry_run=False, yes=False, as_json=True)
     assert rc == 2
     data = json.loads(capsys.readouterr().out)
     assert data["ok"] is False
@@ -246,7 +248,7 @@ def test_active_worktree_protected(
     monkeypatch.chdir(repo)
 
     try:
-        rc = run_clean(branches=True, refs=False, dry_run=False, yes=True, as_json=False)
+        rc = run_clean(branches=True, dry_run=False, yes=True, as_json=False)
         assert rc == 0
 
         r = subprocess.run(
@@ -265,16 +267,13 @@ def test_active_worktree_protected(
         )
 
 
-def test_clean_refs_not_implemented(
-    monkeypatch: pytest.MonkeyPatch, tmp_git_repo_with_stale: Path, capsys
-) -> None:
-    """--refs is advertised but not implemented; it must fail closed with a v3 envelope."""
-    import json
+def test_clean_refs_absent_from_public_contract(tmp_git_repo: Path) -> None:
+    help_result = run_gitwise("clean", "--help", "--json", cwd=tmp_git_repo)
+    assert help_result.returncode == 0
+    options = json.loads(help_result.stdout)["data"]["options"]
+    assert all(option["name"] != "refs" for option in options)
 
-    monkeypatch.chdir(tmp_git_repo_with_stale)
-    rc = run_clean(branches=False, refs=True, dry_run=True, yes=True, as_json=True)
-    assert rc == 1
-    data = json.loads(capsys.readouterr().out)
-    assert data["ok"] is False
-    assert data["command"] == "clean"
-    assert data["errors"][0]["code"] == "not_implemented"
+    schema_result = run_gitwise("schema", "clean", "--json", cwd=tmp_git_repo)
+    assert schema_result.returncode == 0
+    properties = json.loads(schema_result.stdout)["data"]["json_schema"]["properties"]
+    assert "refs" not in properties

{gitwise_cli-0.35.0 → gitwise_cli-0.36.0}/tests/test_snapshot.py

@@ -1,5 +1,6 @@
 """Tests for gitwise snapshot."""
 
+import json
 import time
 
 from conftest import run_gitwise as _run
@@ -12,6 +13,18 @@ def test_snapshot_creates_file(tmp_git_repo):
     assert snapshot.exists()
 
 
+def test_snapshot_uses_agents_layout_when_present(tmp_git_repo):
+    (tmp_git_repo / ".agents").mkdir()
+
+    result = _run("snapshot", "--json", cwd=tmp_git_repo)
+
+    assert result.returncode == 0
+    data = json.loads(result.stdout)["data"]
+    assert data["path"].endswith(".agents/git-snapshot.md")
+    assert (tmp_git_repo / ".agents" / "git-snapshot.md").exists()
+    assert not (tmp_git_repo / ".claude" / "git-snapshot.md").exists()
+
+
 def test_snapshot_has_generated_at(tmp_git_repo):
     _run("snapshot", cwd=tmp_git_repo)
     content = (tmp_git_repo / ".claude" / "git-snapshot.md").read_text()

gitwise_cli-0.36.0/tests/test_update.py

@@ -0,0 +1,65 @@
+"""Tests for the deprecated gitwise update command."""
+
+import json
+from pathlib import Path
+
+import gitwise.update as update_module
+import pytest
+
+
+def _set_install_dir(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, *, source_clone: bool
+) -> Path:
+    package_dir = tmp_path / "gitwise"
+    package_dir.mkdir()
+    if source_clone:
+        (tmp_path / ".git").mkdir()
+    monkeypatch.setattr(update_module, "__file__", str(package_dir / "update.py"))
+    return tmp_path
+
+
+def _assert_upgrade_channels(hints: list[str]) -> None:
+    combined = " ".join(hints)
+    assert "brew upgrade gitwise" in combined
+    assert "uv tool upgrade gitwise-cli" in combined
+
+
+def test_update_non_clone_json_recommends_upgrade_channels(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture
+) -> None:
+    _set_install_dir(monkeypatch, tmp_path, source_clone=False)
+
+    rc = update_module.run_update(as_json=True)
+
+    assert rc == 1
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["errors"][0]["code"] == "update_requires_git_clone"
+    _assert_upgrade_channels(payload["hints"])
+
+
+def test_update_clone_dry_run_json_preserves_behavior_and_recommends_channels(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture
+) -> None:
+    install_dir = _set_install_dir(monkeypatch, tmp_path, source_clone=True)
+
+    rc = update_module.run_update(dry_run=True, as_json=True)
+
+    assert rc == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["data"]["dry_run"] is True
+    assert payload["data"]["dir"] == str(install_dir)
+    _assert_upgrade_channels(payload["hints"])
+
+
+def test_update_clone_dry_run_human_warns_with_upgrade_channels(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture
+) -> None:
+    _set_install_dir(monkeypatch, tmp_path, source_clone=True)
+
+    rc = update_module.run_update(dry_run=True)
+
+    assert rc == 0
+    captured = capsys.readouterr()
+    output = captured.out + captured.err
+    assert "brew upgrade gitwise" in output
+    assert "uv tool upgrade gitwise-cli" in output