pyDiffTools 0.1.58__tar.gz → 0.1.59__tar.gz

{pydifftools-0.1.58/pyDiffTools.egg-info → pydifftools-0.1.59}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyDiffTools
-Version: 0.1.58
+Version: 0.1.59
 Summary: Diff tools
 Author: J M Franck
 License: Copyright (c) 2015, jmfranck
@@ -274,10 +274,20 @@ included are (listed in order of fun/utility):
   retaining the exact command of an existing global ``gd`` alias. If none
   is configured, it installs ``!f() { pydifft gd "$@"; }; f``.
   Configure ``difftool.mygvim.cmd`` for the GUI diff tool.
-- ``pydifft --add_to_git gd pd tree mergein`` installs any selected subset
+- ``pydifft --add_to_git gd pd tree mergein reattach`` installs any selected subset
   of these global Git aliases in one invocation. Installation appears
   alongside the subcommands in root help; the former per-command
   ``--install`` and ``--add-to-git`` flags have been removed.
+- ``pydifft reattach [--path DIRECTORY]`` attaches detached checkouts to
+  branches pointing at exactly their current commits, including initialized
+  submodules recursively. Remote-only matches create local tracking branches.
+  It never resets existing branches or pulls newer commits. With several
+  matches it prefers the origin default branch when possible, otherwise it
+  reports ambiguity and leaves the checkout detached. A local branch with
+  the required name pointing elsewhere is preserved. ``--dry-run`` previews
+  changes, ``--no-recursive`` limits the operation to one repository, and
+  ``--fetch`` refreshes remote refs before matching. Install the global
+  ``git reattach`` alias with ``pydifft --add_to_git reattach``.
 - ``pydifft mergein BRANCH [--remote REMOTE]`` updates an incoming local
   branch without switching branches, then merges it into the current
   branch. Install ``git mergein`` with ``pydifft --add_to_git mergein``.

{pydifftools-0.1.58 → pydifftools-0.1.59}/README.rst

@@ -219,10 +219,20 @@ included are (listed in order of fun/utility):
   retaining the exact command of an existing global ``gd`` alias. If none
   is configured, it installs ``!f() { pydifft gd "$@"; }; f``.
   Configure ``difftool.mygvim.cmd`` for the GUI diff tool.
-- ``pydifft --add_to_git gd pd tree mergein`` installs any selected subset
+- ``pydifft --add_to_git gd pd tree mergein reattach`` installs any selected subset
   of these global Git aliases in one invocation. Installation appears
   alongside the subcommands in root help; the former per-command
   ``--install`` and ``--add-to-git`` flags have been removed.
+- ``pydifft reattach [--path DIRECTORY]`` attaches detached checkouts to
+  branches pointing at exactly their current commits, including initialized
+  submodules recursively. Remote-only matches create local tracking branches.
+  It never resets existing branches or pulls newer commits. With several
+  matches it prefers the origin default branch when possible, otherwise it
+  reports ambiguity and leaves the checkout detached. A local branch with
+  the required name pointing elsewhere is preserved. ``--dry-run`` previews
+  changes, ``--no-recursive`` limits the operation to one repository, and
+  ``--fetch`` refreshes remote refs before matching. Install the global
+  ``git reattach`` alias with ``pydifft --add_to_git reattach``.
 - ``pydifft mergein BRANCH [--remote REMOTE]`` updates an incoming local
   branch without switching branches, then merges it into the current
   branch. Install ``git mergein`` with ``pydifft --add_to_git mergein``.

{pydifftools-0.1.58 → pydifftools-0.1.59/pyDiffTools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyDiffTools
-Version: 0.1.58
+Version: 0.1.59
 Summary: Diff tools
 Author: J M Franck
 License: Copyright (c) 2015, jmfranck
@@ -274,10 +274,20 @@ included are (listed in order of fun/utility):
   retaining the exact command of an existing global ``gd`` alias. If none
   is configured, it installs ``!f() { pydifft gd "$@"; }; f``.
   Configure ``difftool.mygvim.cmd`` for the GUI diff tool.
-- ``pydifft --add_to_git gd pd tree mergein`` installs any selected subset
+- ``pydifft --add_to_git gd pd tree mergein reattach`` installs any selected subset
   of these global Git aliases in one invocation. Installation appears
   alongside the subcommands in root help; the former per-command
   ``--install`` and ``--add-to-git`` flags have been removed.
+- ``pydifft reattach [--path DIRECTORY]`` attaches detached checkouts to
+  branches pointing at exactly their current commits, including initialized
+  submodules recursively. Remote-only matches create local tracking branches.
+  It never resets existing branches or pulls newer commits. With several
+  matches it prefers the origin default branch when possible, otherwise it
+  reports ambiguity and leaves the checkout detached. A local branch with
+  the required name pointing elsewhere is preserved. ``--dry-run`` previews
+  changes, ``--no-recursive`` limits the operation to one repository, and
+  ``--fetch`` refreshes remote refs before matching. Install the global
+  ``git reattach`` alias with ``pydifft --add_to_git reattach``.
 - ``pydifft mergein BRANCH [--remote REMOTE]`` updates an incoming local
   branch without switching branches, then merges it into the current
   branch. Install ``git mergein`` with ``pydifft --add_to_git mergein``.

{pydifftools-0.1.58 → pydifftools-0.1.59}/pyDiffTools.egg-info/SOURCES.txt

@@ -70,6 +70,7 @@ pydifftools/git_gd.py
 pydifftools/git_gd_history.py
 pydifftools/git_gd_image.py
 pydifftools/git_gd_qt.py
+pydifftools/git_reattach.py
 pydifftools/html_comments.py
 pydifftools/html_uncomments.py
 pydifftools/line_alignment.py
@@ -116,6 +117,7 @@ tests/test_git_gd_image.py
 tests/test_git_gd_qt.py
 tests/test_git_mergein.py
 tests/test_git_pdf_diff.py
+tests/test_git_reattach.py
 tests/test_line_alignment.py
 tests/test_pdf_diff.py
 tests/test_qt_lifecycle.py

{pydifftools-0.1.58 → pydifftools-0.1.59}/pydifftools/command_line.py

@@ -36,6 +36,7 @@ from .comment_functions import matchingbrackets
 from .copy_files import copy_image_files
 from .searchacro import replace_acros
 from .rearrange_tex import run as rearrange_tex_run
+from .git_reattach import reattach  # registers branch reattachment
 from .git_gd import gd  # registers git difftool review command
 from .pdf_diff import pd, git_pd  # registers PDF diff command
 from .git_aliases import (
@@ -909,7 +910,7 @@ def build_parser():
     # argparse does not validate REMAINDER choices; main checks them first.
     subparsers.container.add_argument(
         "--add_to_git", nargs=argparse.REMAINDER, choices=list(GIT_ALIASES),
-        help=("Install one or more global Git aliases: gd, pd, tree, mergein "
+        help=("Install one or more global Git aliases: gd, pd, tree, mergein, reattach "
               "(without a subcommand)."),
     )
     for name, spec in _COMMAND_SPECS.items():

{pydifftools-0.1.58 → pydifftools-0.1.59}/pydifftools/git_aliases.py

@@ -11,10 +11,12 @@ GIT_ALIASES = {
     "gd": '!f() { pydifft gd "$@"; }; f',
     "pd": '!f() { pydifft pd --git "$@"; }; f',
     "tree": '!f() { pydifft tree "$@"; }; f',
+    "reattach": '!f() { pydifft reattach "$@"; }; f',
     "mergein": '!f() { pydifft mergein "$@"; }; f',
 }
 
 
+# also used by: pydifftools/command_line.py for global CLI alias installation.
 def install_git_alias(name, command, preserve_existing=False):
     """Install an alias and its completion, optionally retaining its value."""
     if preserve_existing:

pydifftools-0.1.59/pydifftools/git_reattach.py

@@ -0,0 +1,145 @@
+"""Attach detached checkouts without changing the selected commits."""
+
+from pathlib import Path
+import subprocess
+
+from .command_registry import register_command
+
+
+def _git(path, *args, allowed=(0,)):
+    result = subprocess.run(
+        ["git", "-C", str(path), *args], capture_output=True, text=True,
+    )
+    if result.returncode not in allowed:
+        raise RuntimeError(result.stderr.strip() or "Git command failed")
+    return result.stdout.rstrip("\n")
+
+
+@register_command(
+    "reattach detached repositories to matching local or remote branches",
+    description=(
+        "Keep each checkout's current commit and attach a branch whose tip "
+        "matches it exactly. Includes initialized submodules recursively. "
+        "A remote-only match creates a local tracking branch. Existing "
+        "branches are never reset. Ambiguous or unmatched checkouts stay "
+        "detached. Cached remote branches are used unless --fetch is given."
+    ),
+    help={
+        "path": "Repository or a directory inside it (default: current).",
+        "no_recursive": "Only inspect this repository, not its submodules.",
+        "fetch": "Fetch remote branches before looking for matches.",
+        "dry_run": "Show proposed switches without changing anything.",
+    },
+)
+def reattach(path=".", no_recursive=False, fetch=False, dry_run=False):
+    """Find exact branch-tip matches, preserving commits and working files."""
+    if fetch and dry_run:
+        raise SystemExit("reattach: --fetch cannot be used with --dry-run")
+    try:
+        root = Path(_git(path, "rev-parse", "--show-toplevel"))
+        paths = [root]
+        if not no_recursive:
+            children = _git(
+                root, "submodule", "foreach", "--quiet", "--recursive",
+                'printf "%s\\0" "$PWD"',
+            )
+            paths.extend(Path(p) for p in children.split("\0") if p)
+        failed = False
+        for checkout in paths:
+            label = str(checkout)
+            try:
+                if _git(
+                    checkout, "symbolic-ref", "--quiet", "HEAD",
+                    allowed=(0, 1),
+                ):
+                    print(f"{label}: already on a branch; unchanged")
+                    continue
+                if fetch:
+                    _git(checkout, "fetch", "--all", "--prune",
+                         "--no-recurse-submodules")
+                head = _git(checkout, "rev-parse", "HEAD")
+                # {{{ ask Git for exact matches, excluding symbolic refs
+                refs = _git(
+                    checkout, "for-each-ref",
+                    "--format=%(refname)%00%(symref)", "--points-at", head,
+                    "refs/heads/", "refs/remotes/",
+                )
+                matches = [
+                    line.split("\0")[0] for line in refs.splitlines()
+                    if line.endswith("\0")
+                ]
+                local = [r for r in matches if r.startswith("refs/heads/")]
+                remote = [r for r in matches
+                          if r.startswith("refs/remotes/")]
+                default = _git(
+                    checkout, "symbolic-ref", "--quiet",
+                    "refs/remotes/origin/HEAD", allowed=(0, 1),
+                )
+                default_name = default.removeprefix("refs/remotes/origin/")
+                branch = None
+                upstream = None
+                if local:
+                    preferred = "refs/heads/" + default_name
+                    if preferred in local:
+                        branch = default_name
+                    elif len(local) == 1:
+                        branch = local[0].removeprefix("refs/heads/")
+                elif remote:
+                    # Derive names from configured remotes, retaining slashes
+                    # in branch names and allowing slashes in remote names.
+                    remotes = sorted(
+                        _git(checkout, "remote").splitlines(),
+                        key=len, reverse=True,
+                    )
+                    candidates = {}
+                    for ref in remote:
+                        for name in remotes:
+                            prefix = f"refs/remotes/{name}/"
+                            if ref.startswith(prefix):
+                                candidates[ref] = ref[len(prefix):]
+                                break
+                    if default in candidates:
+                        upstream = default
+                    elif len(candidates) == 1:
+                        upstream = next(iter(candidates))
+                    elif len(set(candidates.values())) == 1:
+                        name = next(iter(candidates.values()))
+                        preferred = "refs/remotes/origin/" + name
+                        if preferred in candidates:
+                            upstream = preferred
+                    if upstream:
+                        branch = candidates[upstream]
+                        existing = _git(
+                            checkout, "show-ref", "--verify", "--hash",
+                            f"refs/heads/{branch}", allowed=(0, 1, 128),
+                        )
+                        if existing:
+                            print(
+                                f"{label}: local {branch} points elsewhere; "
+                                "left detached without resetting it"
+                            )
+                            continue
+                # }}}
+                if branch is None:
+                    reason = "ambiguous branch matches" if matches else (
+                        "no branch tip matches this commit"
+                    )
+                    print(f"{label}: {reason}; left detached")
+                    continue
+                action = "create tracking branch" if upstream else "switch to"
+                print(f"{label}: {action} {branch}")
+                if not dry_run:
+                    if upstream:
+                        _git(checkout, "switch", "--track", "-c", branch,
+                             upstream)
+                    else:
+                        _git(checkout, "switch", "--no-guess", "--", branch)
+                    if _git(checkout, "rev-parse", "HEAD") != head:
+                        raise RuntimeError("branch moved during reattachment")
+            except RuntimeError as exc:
+                print(f"{label}: {exc}")
+                failed = True
+        if failed:
+            raise SystemExit(1)
+    except (OSError, RuntimeError) as exc:
+        raise SystemExit(f"reattach: {exc}") from None

{pydifftools-0.1.58 → pydifftools-0.1.59}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyDiffTools"
-version = "0.1.58"
+version = "0.1.59"
 authors = [{ name = "J M Franck" }]
 description = "Diff tools"
 readme = "README.rst"

pydifftools-0.1.59/tests/test_git_reattach.py

@@ -0,0 +1,186 @@
+"""Reattachment against real repositories, including remote-only branches."""
+
+import os
+from pathlib import Path
+import subprocess
+import sys
+import time
+
+import pytest
+
+from pydifftools.git_reattach import reattach
+from pydifftools import command_line
+
+
+def git(path, *args):
+    return subprocess.check_output(
+        ["git", "-C", str(path), *map(str, args)],
+        stderr=subprocess.STDOUT, text=True,
+    ).strip()
+
+
+@pytest.fixture
+def project(tmp_path, monkeypatch):
+    monkeypatch.setenv("GIT_CONFIG_GLOBAL", str(tmp_path / "global"))
+    monkeypatch.setenv("GIT_CONFIG_NOSYSTEM", "1")
+    monkeypatch.setenv("GIT_AUTHOR_NAME", "Test")
+    monkeypatch.setenv("GIT_AUTHOR_EMAIL", "test@example.invalid")
+    monkeypatch.setenv("GIT_COMMITTER_NAME", "Test")
+    monkeypatch.setenv("GIT_COMMITTER_EMAIL", "test@example.invalid")
+    remote = tmp_path / "remote.git"
+    seed = tmp_path / "seed"
+    work = tmp_path / "work space"
+    git(tmp_path, "init", "--bare", "--initial-branch=main", remote)
+    git(tmp_path, "clone", remote, seed)
+    (seed / "file").write_text("main\n")
+    git(seed, "add", "file")
+    git(seed, "commit", "-m", "main")
+    git(seed, "checkout", "-b", "work/topic")
+    (seed / "file").write_text("topic\n")
+    git(seed, "commit", "-am", "topic")
+    git(seed, "push", "origin", "main", "work/topic")
+    git(tmp_path, "clone", remote, work)
+    git(work, "checkout", "--detach", "origin/work/topic")
+    return seed, work
+
+
+def test_remote_only_match_tracks_and_preserves_files(project):
+    _, work = project
+    before = git(work, "rev-parse", "HEAD")
+    (work / "file").write_text("uncommitted edit\n")
+    (work / "untracked").write_text("keep\n")
+    reattach(str(work))
+    assert git(work, "branch", "--show-current") == "work/topic"
+    assert git(work, "rev-parse", "--abbrev-ref", "@{upstream}") == (
+        "origin/work/topic"
+    )
+    assert git(work, "rev-parse", "HEAD") == before
+    assert (work / "file").read_text() == "uncommitted edit\n"
+    assert (work / "untracked").read_text() == "keep\n"
+    reattach(str(work))
+    assert git(work, "rev-parse", "HEAD") == before
+
+
+def test_local_match_and_dry_run(project):
+    _, work = project
+    git(work, "branch", "topic-local", "HEAD")
+    reattach(str(work), dry_run=True)
+    assert git(work, "branch", "--show-current") == ""
+    reattach(str(work))
+    assert git(work, "branch", "--show-current") == "topic-local"
+
+
+def test_origin_default_disambiguates_local_branches(project):
+    _, work = project
+    git(work, "checkout", "--detach", "origin/main")
+    git(work, "branch", "alternative", "HEAD")
+    reattach(str(work))
+    assert git(work, "branch", "--show-current") == "main"
+
+
+def test_default_remote_branch_wins_over_other_remote_matches(project):
+    _, work = project
+    git(work, "checkout", "--detach", "origin/main")
+    git(work, "branch", "-D", "main")
+    git(work, "update-ref", "refs/remotes/origin/alternative", "HEAD")
+    reattach(str(work))
+    assert git(work, "branch", "--show-current") == "main"
+    assert git(work, "rev-parse", "--abbrev-ref", "@{u}") == "origin/main"
+
+
+def test_ambiguous_remote_matches_are_not_chosen_arbitrarily(project, capsys):
+    _, work = project
+    git(work, "update-ref", "refs/remotes/origin/also-topic", "HEAD")
+    reattach(str(work))
+    assert git(work, "branch", "--show-current") == ""
+    assert "ambiguous" in capsys.readouterr().out
+
+
+def test_existing_local_branch_is_never_reset(project, capsys):
+    _, work = project
+    git(work, "branch", "work/topic", "origin/main")
+    before = git(work, "rev-parse", "work/topic")
+    reattach(str(work))
+    assert git(work, "branch", "--show-current") == ""
+    assert git(work, "rev-parse", "work/topic") == before
+    assert "points elsewhere" in capsys.readouterr().out
+
+
+def test_no_match_stays_at_recorded_commit(project):
+    _, work = project
+    (work / "file").write_text("unpublished\n")
+    git(work, "commit", "-am", "unpublished")
+    before = git(work, "rev-parse", "HEAD")
+    reattach(str(work))
+    assert git(work, "branch", "--show-current") == ""
+    assert git(work, "rev-parse", "HEAD") == before
+
+
+def test_non_origin_remote_and_branch_with_slash(project):
+    _, work = project
+    git(work, "remote", "rename", "origin", "upstream")
+    reattach(str(work))
+    assert git(work, "rev-parse", "--abbrev-ref", "@{u}") == (
+        "upstream/work/topic"
+    )
+
+
+def test_recursive_submodule_and_cli_registration(project, tmp_path):
+    seed, work = project
+    parent = tmp_path / "parent"
+    git(tmp_path, "init", "--initial-branch=main", parent)
+    git(parent, "-c", "protocol.file.allow=always", "submodule", "add",
+        str(seed), "child with spaces")
+    child = parent / "child with spaces"
+    git(child, "checkout", "--detach", "origin/work/topic")
+    git(child, "branch", "-D", "work/topic")
+    git(parent, "commit", "-am", "child")
+    args = command_line.build_parser().parse_args(
+        ["reattach", "--path", str(parent)]
+    )
+    args._handler(path=args.path, no_recursive=args.no_recursive,
+                  fetch=args.fetch, dry_run=args.dry_run)
+    assert git(child, "branch", "--show-current") == "work/topic"
+    assert git(parent, "branch", "--show-current") == "main"
+    assert git(child, "rev-parse", "HEAD") == git(work, "rev-parse", "HEAD")
+
+
+def test_checked_out_branch_elsewhere_is_not_stolen(project, tmp_path):
+    _, work = project
+    git(work, "branch", "topic-local", "HEAD")
+    git(work, "worktree", "add", tmp_path / "other", "topic-local")
+    with pytest.raises(SystemExit):
+        reattach(str(work))
+    assert git(work, "branch", "--show-current") == ""
+
+
+def test_fetch_finds_remote_only_match(project):
+    _, work = project
+    git(work, "update-ref", "-d", "refs/remotes/origin/work/topic")
+    reattach(str(work), fetch=True)
+    assert git(work, "branch", "--show-current") == "work/topic"
+    assert git(work, "rev-parse", "--abbrev-ref", "@{u}") == (
+        "origin/work/topic"
+    )
+
+
+def test_installed_git_alias_forwards_options(project, tmp_path, monkeypatch):
+    _, work = project
+    launcher = tmp_path / "pydifft"
+    launcher.write_text(
+        f"#!{sys.executable}\n"
+        "from pydifftools.command_line import main\nmain()\n"
+    )
+    launcher.chmod(0o755)
+    monkeypatch.setenv("PATH", str(tmp_path) + os.pathsep + os.environ["PATH"])
+    monkeypatch.setenv("PYTHONPATH", str(Path(__file__).resolve().parents[1]))
+    monkeypatch.setenv(
+        "PYDIFFTOOLS_UPDATE_CHECK_LAST_RAN_UTC_DATE",
+        time.strftime("%Y-%m-%d", time.gmtime()),
+    )
+    monkeypatch.chdir(work)
+    command_line.main(["--add_to_git", "reattach"])
+    git(work, "reattach", "--dry-run", "--no-recursive")
+    assert git(work, "branch", "--show-current") == ""
+    git(work, "reattach", "--no-recursive")
+    assert git(work, "branch", "--show-current") == "work/topic"