git-project 0.0.37__tar.gz → 0.0.38__tar.gz

{git_project-0.0.37 → git_project-0.0.38}/.gitignore

@@ -26,3 +26,25 @@
 
 # Python egg metadata, regenerated from source files by setuptools.
 /*.egg-info
+
+# Python bytecode cache directories.
+__pycache__/
+
+# Version file generated by vcs-versioning.
+/_version.py
+
+# Setuptools build folder.
+/build/
+
+# Editor backup files.
+*~
+
+# Coverage data.  The coverage config sets parallel, so each run also writes
+# .coverage.<host>.<pid>.<random> files for coverage combine.
+.coverage*
+
+# Coverage HTML report.
+/htmlcov/
+
+# Sphinx build output.
+/docs/_build/

git_project-0.0.38/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: git-project
+Version: 0.0.38
+Summary: The extensible stupid project manager
+Author-email: "David A. Greene" <dag@obbligato.org>
+License-Expression: AGPL-3.0-or-later
+License-File: COPYING
+Keywords: development,git,project
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Requires-Dist: progressbar2>=4.4.2
+Requires-Dist: pygit2>=1.18.2
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-console-scripts; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: setuptools; extra == 'test'
+Description-Content-Type: text/x-rst
+
+
+===================================================
+git-project - The extensible stupid project manager
+===================================================
+
+|VersionImageLink|_
+
+|PythonVersionImageLink|_
+
+.. |VersionImageLink| image:: https://img.shields.io/pypi/v/git-project.svg
+.. _VersionImageLink: https://pypi.org/project/git-project
+.. |PythonVersionImageLink| image:: https://img.shields.io/pypi/pyversions/git-project.svg
+.. _PythonVersionImageLink: https://pypi.org/project/git-project
+
+
+-------
+
+.. contents:: Table of Contents
+
+
+Installation
+============
+::
+
+   pip install git-project
+   pip install git-project-core-plugins
+
+Description
+===========
+
+git-project is a git extension to manage development of a project hosted in a
+git repository.  By itself git-project does almost nothing.  Its functionality
+is enhanced by plugins.
+
+`git-project-core-plugins
+<http://www.github.com/greened/git-project-core-plugins>`_ provides a set of
+basic functionality and should almost always be installed alongside git-project.
+
+Conventions
+===========
+
+Symlinks identiy projects to the ``git-project`` command.  For example, if
+``git-fizzbin`` is symlinked to ``git-project``, then ``git fizzbin <command>``
+will invoke ``git-project`` with ``fizzbin`` as the "active project."  To
+emphasize this, we show git-project commands with a generic ``<project>``
+identifier::
+
+  git <project> --help
+
+Discussion
+==========
+
+With git-project and its core plugins you can:
+
+* Initialize a development environment at clone time (or after clone time)
+* Manage branches
+* Manage worktrees
+* Set and invoke commands
+
+git-project is intended to make switching between active 'tasks' in a repository
+simple and fast, without losing the progress context of existing tasks.  For
+example the core plugins set up build environments such that switching among
+projects and worktrees does not result in "rebuilding the world."  Builds can be
+configured to invoke complex commands via a convenient name (e.g. ``git
+<project> build debug``)
+
+Substitution variables
+======================
+
+Commands that allow substitution take a form ``{varname}`` in their configured
+textual representation and substitute it with the value of ``varname``.
+``varname`` can be any configured value under ``<project>``, for example::
+
+    [project]
+        myvar = value
+
+``git-project`` has several built-in substitution variables that various
+commands and plugins can use:
+
+``branch``
+    The name of the currently checked-out branch
+``gitdir``
+    The value of ``GITDIR``
+``git_common_dir``
+    The value of ``GIT_COMMON_DIR``
+``project``
+    The value of ``<project>``
+
+License
+=======
+`git-project` is distributed under the terms of the `GNU General Public License v3.0 or later`_.
+
+.. _`GNU General Public License v3.0 or later`: https://spdx.org/licenses/GPL-3.0-or-later.html
+
+
+..
+    SPDX-FileCopyrightText: 2024-present David A. Greene <dag@obbligato.org>
+
+..
+    SPDX-License-Identifier: AGPL-3.0-or-later
+
+..
+    Copyright 2023 David A. Greene
+
+..
+    This file is part of git-project
+
+..
+    git-project is free software: you can redistribute it and/or modify it under
+    the terms of the GNU Affero General Public License as published by the Free
+    Software Foundation, either version 3 of the License, or (at your option)
+    any later version.
+
+..
+    This program is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+    more details.
+
+..
+    You should have received a copy of the GNU Affero General Public License
+    along with git-project. If not, see <https://www.gnu.org/licenses/>.
+
+Authors
+=======
+*git-project* is written and maintained by |author|.
+
+.. |author| replace:: `David Greene`_
+.. _David Greene: https://github.com/greened
+

{git_project-0.0.37 → git_project-0.0.38}/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.0.37'
-__version_tuple__ = version_tuple = (0, 0, 37)
+__version__ = version = '0.0.38'
+__version_tuple__ = version_tuple = (0, 0, 38)
 
 __commit_id__ = commit_id = None

git_project-0.0.38/docs/changelog.rst

@@ -0,0 +1,84 @@
+..
+    SPDX-FileCopyrightText: 2023-present David A. Greene <dag@obbligato.org>
+
+..
+    SPDX-License-Identifier: AGPL-3.0-or-later
+
+..
+    Copyright 2023 David A. Greene
+
+..
+    This file is part of git-project
+
+..
+    git-project is free software: you can redistribute it and/or modify it under
+    the terms of the GNU Affero General Public License as published by the Free
+    Software Foundation, either version 3 of the License, or (at your option)
+    any later version.
+
+..
+    This program is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+    more details.
+
+..
+    You should have received a copy of the GNU Affero General Public License
+    along with git-project. If not, see <https://www.gnu.org/licenses/>.
+
+ChangeLog
+=========
+`Unreleased`_
+-------------
+
+`0.0.38`_ - 2026-09-24
+----------------------
+Added
+.....
+- ``prune_branch`` takes a ``keep_remote_branch`` keyword. It previously
+  deleted the branch from every project remote as well as locally, so retiring
+  a local branch destroyed the remote copy with it.
+
+Changed
+.......
+- Python 3.10 or later is now required. ``list_heads`` needs it, and 1.15.1 is
+  the last pygit2 that supports 3.9, so on 3.9 there is no installable pygit2
+  carrying the API.
+- pygit2 1.18.2 or later is now required, up from 1.15.1. The old range still
+  resolved, so the package installed cleanly and then raised ``AttributeError``
+  in use.
+
+Fixed
+.....
+- ``git <project> clone`` did not work at all. ``Git.clone`` required an ssh ID,
+  so the clone paths raised ``TypeError``. The ID is now optional, and a
+  keypair is simply not offered when there is none. This also fixes
+  ``fetch_remote``, ``remote_branch_exists`` and ``delete_remote_branch`` for
+  any repository that never set ``ssh.id``.
+- ``remote_branch_exists`` called ``Remote.ls_remotes()``, which pygit2 1.20
+  removed. It now calls ``list_heads()`` and reads the fields off the
+  ``RemoteHead`` objects.
+- A ``Git`` re-pointed at a path with no repository stayed attached to the
+  previous one. ``has_repo`` answered ``True``, so later work ran against the
+  repository the caller had left. It now detaches, and ``has_repo`` answers
+  ``False``.
+- A ``Git`` built outside any repository named a missing private field rather
+  than the real fault. ``reinit`` set the repository only when discovery
+  succeeded, so most accessors raised ``AttributeError``. ``config`` named
+  ``_config`` rather than ``_repo``, and ``committish_exists`` raised nothing
+  at all and answered ``False``, which said the committish was absent. The
+  repository accessors now raise ``GitProjectException`` naming the path that
+  was searched.
+- The Issues link on the PyPI project page returned 404. The URL named
+  ``unknown/greened`` instead of ``greened/git-project``, a leftover from
+  hatch's project template.
+- The PyPI long description stopped at the separator after the badges, so
+  everything from Installation on went unpublished. A second readme fragment
+  now carries the rest.
+- The Sphinx docs rendered no module documentation at all. ``automodule`` was
+  asked for ``git-project``, which is not an importable name; it now asks for
+  ``git_project``. No declared environment supplied Sphinx either, so a
+  ``docs`` environment with Sphinx is now declared.
+
+.. _Unreleased: https://github.com/greened/git-project/compare/v0.0.38...HEAD
+.. _0.0.38: https://github.com/greened/git-project/compare/v0.0.37...v0.0.38

{git_project-0.0.37 → git_project-0.0.38}/docs/intro.rst

@@ -26,4 +26,4 @@
     You should have received a copy of the GNU Affero General Public License
     along with git-project. If not, see <https://www.gnu.org/licenses/>.
 
-.. automodule:: git-project
+.. automodule:: git_project

{git_project-0.0.37 → git_project-0.0.38}/pyproject.toml

@@ -31,7 +31,7 @@ name = "git-project"
 dynamic = ["dependencies", "readme", "version"]
 description = "The extensible stupid project manager"
 license = "AGPL-3.0-or-later"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 authors = [
     { name = "David A. Greene", email = "dag@obbligato.org" },
 ]
@@ -45,7 +45,8 @@ classifiers = [
     "Environment :: Console",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
-    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
     "Topic :: Software Development :: Version Control :: Git",
 ]
 
@@ -62,7 +63,7 @@ git-project = "git_project.main:main"
 
 [project.urls]
 Documentation = "https://github.com/greened/git-project#readme"
-Issues = "https://github.com/unknown/greened/issues"
+Issues = "https://github.com/greened/git-project/issues"
 Source = "https://github.com/greened/git-project"
 
 [tool.hatch.version]
@@ -70,6 +71,9 @@ source = "vcs"
 
 [tool.hatch.envs.default]
 dependencies = [
+  # Provides the "git-project.plugins" entry points the CLI tests dispatch
+  # through; without them argparse offers an empty subcommand list.
+  "git-project-core-plugins",
   "coverage[toml]>=6.5",
   "pytest",
   "pytest-console-scripts",
@@ -88,7 +92,7 @@ cov = [
 ]
 
 [[tool.hatch.envs.all.matrix]]
-python = ["3.9", "3.10", "3.11"]
+python = ["3.10", "3.11"]
 
 [tool.hatch.envs.lint]
 detached = true
@@ -113,14 +117,27 @@ all = [
   "typing",
 ]
 
+[tool.hatch.envs.docs]
+# NOT detached: autodoc imports the package, because docs/intro.rst pulls the
+# module docstring in with automodule rather than keeping a second copy. A
+# detached env would build with the package absent and the directive would fail.
+dependencies = [
+  "sphinx>=7",
+]
+[tool.hatch.envs.docs.scripts]
+build = "sphinx-build -M html docs docs/_build"
+clean = "sphinx-build -M clean docs docs/_build"
+
 [tool.black]
-target-version = ["py37"]
+target-version = ["py310"]
 line-length = 120
 skip-string-normalization = true
 
 [tool.ruff]
-target-version = "py37"
+target-version = "py310"
 line-length = 120
+
+[tool.ruff.lint]
 select = [
   "A",
   "ARG",
@@ -163,13 +180,13 @@ unfixable = [
   "F401",
 ]
 
-[tool.ruff.isort]
+[tool.ruff.lint.isort]
 known-first-party = ["git-project"]
 
-[tool.ruff.flake8-tidy-imports]
+[tool.ruff.lint.flake8-tidy-imports]
 ban-relative-imports = "all"
 
-[tool.ruff.per-file-ignores]
+[tool.ruff.lint.per-file-ignores]
 # Tests can use magic values, assertions, and relative imports
 "tests/**/*" = ["PLR2004", "S101", "TID252"]
 
@@ -213,6 +230,21 @@ text = """
 
 """
 
+# The rest of the module docstring: everything past the badges. Without this
+# the description stopped at the separator above, so Installation and the whole
+# body were never published. The docstring is the single source; docs/intro.rst
+# pulls the same text in with automodule.
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "src/git_project/__init__.py"
+start-after = "-------\n"
+end-before = "\"\"\""
+
+# Fragments are concatenated verbatim and the docstring ends in an indented
+# block, so without a blank line the next fragment unindents into it. That is an
+# RST error and PyPI rejects a description that fails to render.
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+text = "\n"
+
 [[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
 path = "docs/authors.rst"
 end-before = "A full list of contributors"

{git_project-0.0.37 → git_project-0.0.38}/requirements.txt

@@ -19,4 +19,4 @@
 # with git-project. If not, see <https://www.gnu.org/licenses/>.
 
 progressbar2>=4.4.2
-pygit2>=1.15.1
+pygit2>=1.18.2

{git_project-0.0.37 → git_project-0.0.38}/src/git_project/commandline.py

@@ -47,11 +47,7 @@ import subprocess
 import sys
 import urllib.parse
 
-try:
-    from importlib import metadata
-except ImportError:
-    # Running on pre-3.8 Python; use importlib-metadata package
-    import importlib_metadata as metadata
+from importlib import metadata
 
 from .parsermanager import ParserManager
 

{git_project-0.0.37 → git_project-0.0.38}/src/git_project/git.py

@@ -32,23 +32,32 @@ import urllib
 from .exception import GitProjectException
 from .shell import capture_command
 
-# Python 3.9 things so we don't actually need 3.9.
-
-def _is_relative_to(path, other):
-    try:
-        path.relative_to(other)
-        return True
-    except ValueError:
-        return False
-
 # Git commands
 #
 class Git(object):
     """A facade over a lower-level interface to git providing interfaces needed to
     implement git-project functionality."""
 
+    @staticmethod
+    def _ssh_credentials(ssh_id, username_from_url, allowed_types):
+        """Return the credentials to authenticate with, or None if we have none to
+        offer.  Name the keypair under ~/.ssh for the given ssh ID.  Offer no
+        keypair without an ssh ID.
+
+        """
+        if ssh_id and allowed_types & pygit2.enums.CredentialType.SSH_KEY:
+            return pygit2.Keypair(
+                username_from_url,
+                str(Path.home() / '.ssh' / f'{ssh_id}.pub'),
+                str(Path.home() / '.ssh' / ssh_id),
+                ''
+            )
+        elif allowed_types & pygit2.enums.CredentialType.USERNAME:
+            return pygit2.Username(username_from_url)
+        return None
+
     class RemoteCallbacks(pygit2.RemoteCallbacks):
-        def __init__(self, ssh_id: str):
+        def __init__(self, ssh_id: str | None):
             self.started_transfer = False
             self.transfer_done = False
 
@@ -60,16 +69,8 @@ class Git(object):
             self.ssh_id = ssh_id
 
         def credentials(self, url, username_from_url, allowed_types):
-            if allowed_types & pygit2.enums.CredentialType.SSH_KEY:
-                return pygit2.Keypair(
-                    username_from_url,
-                    str(Path.home() / '.ssh' / f'{self.ssh_id}.pub'),
-                    str(Path.home() / '.ssh' / self.ssh_id),
-                    ''
-                )
-            elif allowed_types & pygit2.enums.CredentialType.USERNAME:
-                return pygit2.Username(username_from_url)
-            return None
+            return Git._ssh_credentials(self.ssh_id, username_from_url,
+                                        allowed_types)
 
         def sideband_progress(self, message):
             print(f'Remote: {message}')
@@ -377,21 +378,13 @@ class Git(object):
                 del self._sections[section_name]
 
     class RemoteBranchDeleteCallback(pygit2.RemoteCallbacks):
-        def __init__(self, ssh_id: str):
+        def __init__(self, ssh_id: str | None):
             self.ssh_id = ssh_id
 
         """Check the result of remove branch prune operations."""
         def credentials(self, url, username_from_url, allowed_types):
-            if allowed_types & pygit2.enums.CredentialType.SSH_KEY:
-                return pygit2.Keypair(
-                    username_from_url,
-                    str(Path.home() / '.ssh' / f'{self.ssh_id}.pub'),
-                    str(Path.home() / '.ssh' / self.ssh_id),
-                    ''
-                )
-            elif allowed_types & pygit2.enums.CredentialType.USERNAME:
-                return pygit2.Username(username_from_url)
-            return None
+            return Git._ssh_credentials(self.ssh_id, username_from_url,
+                                        allowed_types)
 
         def push_update_reference(self, refname, message):
             if message is not None:
@@ -399,40 +392,66 @@ class Git(object):
                                 format(message))
 
     class LsRemotesCallbacks(pygit2.RemoteCallbacks):
-        def __init__(self, ssh_id: str):
+        def __init__(self, ssh_id: str | None):
             self.ssh_id = ssh_id
 
         def credentials(self, url, username_from_url, allowed_types):
-            if allowed_types & pygit2.enums.CredentialType.SSH_KEY:
-                return pygit2.Keypair(
-                    username_from_url,
-                    str(Path.home() / '.ssh' / f'{self.ssh_id}.pub'),
-                    str(Path.home() / '.ssh' / self.ssh_id),
-                    ''
-                )
-            elif allowed_types & pygit2.enums.CredentialType.USERNAME:
-                return pygit2.Username(username_from_url)
-            return None
+            return Git._ssh_credentials(self.ssh_id, username_from_url,
+                                        allowed_types)
 
     # Repository-wide info
     def __init__(self):
         self.reinit(Path.cwd())
 
-    def reinit(self, gitdir: Path):
-        repo_path = pygit2.discover_repository(gitdir)
+    def reinit(self, gitdir: Path | str):
+        """Attach to the repository that holds gitdir, or to no repository.
+
+        A caller may build a Git outside any repository.  Record the path we
+        searched and leave the repository empty.  has_repo then answers False,
+        and each repository accessor raises an error that names the path.
+
+        """
+        self._search_path = Path(gitdir).resolve()
+        repo_path = pygit2.discover_repository(self._search_path)
         if repo_path:
-            self._repo = pygit2.Repository(repo_path)
-            self._config = self.Config(self, self._repo.config)
+            self._repository = pygit2.Repository(repo_path)
+            self._config = self.Config(self, self._repository.config)
             self.validate_config()
+        else:
+            self._repository = None
+            self._config = None
+
+    def _no_repository_error(self):
+        """Return the error to raise when there is no repository."""
+        return GitProjectException(
+            f'No git repository at {self._search_path} or any parent')
+
+    @property
+    def _repo(self):
+        """Return the pygit2 repository.  Raise if there is none.
+
+        Each accessor reads the repository through this property, so one guard
+        gives them all the same legible error.
+
+        """
+        if self._repository is None:
+            raise self._no_repository_error()
+        return self._repository
 
     @property
     def config(self):
-        """Return the config of the repository."""
+        """Return the config of the repository.
+
+        Raise GitProjectException when there is no repository.
+
+        """
+        if self._repository is None or self._config is None:
+            raise self._no_repository_error()
         return self._config
 
     def has_repo(self):
         """Return whether we are attached to a repository."""
-        return hasattr(self, '_repo')
+        return self._repository is not None
 
     def reload_config(self):
         """Reload the config."""
@@ -509,7 +528,7 @@ class Git(object):
         for name in self._repo.list_worktrees():
             worktree = self._repo.lookup_worktree(name)
             path = Path(worktree.path).resolve()
-            if path == cwd or _is_relative_to(cwd, path):
+            if path == cwd or cwd.is_relative_to(path):
                 return name
 
         return None
@@ -522,13 +541,13 @@ class Git(object):
         for name in self._repo.list_worktrees():
             worktree = self._repo.lookup_worktree(name)
             path = Path(worktree.path).resolve()
-            if path == cwd or _is_relative_to(cwd, path):
+            if path == cwd or cwd.is_relative_to(path):
                 return str(path)
 
         # See if we have a GITDIR somewhere along the way.
         gitdir = Path(self._repo.path).resolve()
         while True:
-            if gitdir != cwd and _is_relative_to(gitdir, cwd):
+            if gitdir != cwd and gitdir.is_relative_to(cwd):
                 return cwd
             parent = cwd.parent
             if parent == cwd:
@@ -567,8 +586,13 @@ class Git(object):
 
     def committish_exists(self, committish):
         """Return whether the committish exists in the repository."""
+        # Read the repository before the try.  The bare except below would
+        # otherwise swallow the no-repository error and answer False, which
+        # says the committish is absent rather than that there is nothing to
+        # look in.
+        repo = self._repo
         try:
-            self._repo.revparse_single(committish)
+            repo.revparse_single(committish)
             return True
         except:
             return False
@@ -770,16 +794,22 @@ class Git(object):
             result = branch.upstream.branch_name
         return result
 
-    def clone(self, url, ssh_id, path=None, bare=False):
-        """Clone a respository at the given url, making a bare clone if specified."""
+    def clone(self, url, ssh_id=None, path=None, bare=False):
+        """Clone a repository at the given url, making a bare clone if specified.
+        Authenticate with the ssh ID if one is given.  A clone runs before there
+        is a repository config to read one from, so the caller supplies it.
+        Without an ssh ID we offer no key, which suits a local or an anonymous
+        url.  An ssh url instead fails to authenticate.
+
+        """
         parsed_url = urllib.parse.urlparse(url)
         url_path = Path(parsed_url.path).resolve()
         url_name = url_path.name
         target_path = path if path else str(Path.cwd() / url_name)
 
         callbacks = Git.RemoteCallbacks(ssh_id)
-        self._repo = pygit2.clone_repository(url, target_path, bare, callbacks=callbacks)
-        self._config = self.Config(self, self._repo.config)
+        self._repository = pygit2.clone_repository(url, target_path, bare, callbacks=callbacks)
+        self._config = self.Config(self, self._repository.config)
 
         return str(Path(target_path).resolve())
 
@@ -835,18 +865,18 @@ class Git(object):
         self._repo.branches.delete(branch_name)
 
     def remote_branch_exists(self, branch_name, remote):
-        """Return whethe the given branch exists on the given remote."""
+        """Return whether the given branch exists on the given remote."""
         refname = self.branch_name_to_refname(branch_name)
         # FIXME: This is likely to be something like
         # refs/remotes/<remote>/<branch_name> but that is not what it's called
-        # in the ls_remotes call.  There doesn't seem to be a way to get the
+        # in the list_heads call.  There doesn't seem to be a way to get the
         # (local) name of the branch on the remote side.  Assume for now that
         # it's the same as our local name.
         remote_refname = self.get_remote_push_refname(refname, remote)
-        for item in self._repo.remotes[remote].ls_remotes(
+        for item in self._repo.remotes[remote].list_heads(
                 callbacks=Git.LsRemotesCallbacks(self.get_ssh_id())
         ):
-            if not item['local'] and item['name'] == refname:
+            if not item.local and item.name == refname:
                 return True
         return False