git-project-core-plugins 0.0.21__tar.gz → 0.0.23__tar.gz

git_project_core_plugins-0.0.23/.git

@@ -0,0 +1 @@
+gitdir: /home/dag/src/git-project-core-plugins/.git/worktrees/master/

{git_project_core_plugins-0.0.21 → git_project_core_plugins-0.0.23}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: git-project-core-plugins
-Version: 0.0.21
+Version: 0.0.23
 Summary: The extensible stupid project manager - core functionality
 Author-email: "David A. Greene" <dag@obbligato.org>
 License-Expression: AGPL-3.0-or-later
@@ -12,9 +12,9 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Topic :: Software Development :: Version Control :: Git
-Requires-Python: >=3
-Requires-Dist: git-project>=0.0.24
-Requires-Dist: progressbar
+Requires-Python: >=3.9
+Requires-Dist: git-project>=0.0.30
+Requires-Dist: pytest-console-scripts
 Provides-Extra: test
 Requires-Dist: git-project; extra == 'test'
 Requires-Dist: pytest; extra == 'test'

{git_project_core_plugins-0.0.21 → git_project_core_plugins-0.0.23}/_version.py

@@ -1,8 +1,13 @@
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
 else:
     VERSION_TUPLE = object
@@ -12,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.0.21'
-__version_tuple__ = version_tuple = (0, 0, 21)
+__version__ = version = '0.0.23'
+__version_tuple__ = version_tuple = (0, 0, 23)

git_project_core_plugins-0.0.23/git_project_core_plugins.egg-info/PKG-INFO

@@ -0,0 +1,496 @@
+Metadata-Version: 2.1
+Name: git_project_core_plugins
+Version: 0.0.19
+Summary: Core functionality for git-project
+Home-page: http://github.com/greened/git-project-core-plugins
+Author: David A. Greene
+Author-email: dag@obbligato.org
+License: GPLv3+
+Keywords: git project development
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3
+Description-Content-Type: text/x-rst
+License-File: COPYING
+Requires-Dist: git_project>=0.0.17
+Requires-Dist: progressbar2
+Requires-Dist: pygit2
+
+************************
+git-project-core-plugins
+************************
+
+Plugins for `git-project <http://www.github.com/greened/git-project>`_
+
+This is a set of basic plugins to manage several aspects of projects kept within
+git repositories.  These plugins include commands to:
+
+#. Configure git-project and its various plugins
+#. Clone repositories
+#. Manage branches
+#. Manage worktrees
+#. Run commands (e.g configure/build/install)
+
+Setup
+=====
+
+``pip install git-project-core-plugins``
+
+Commands
+========
+
+These plugins add a number of commands to git-project.  Each command has an
+associated ``--help`` option to describe its function and options.  There is
+also a `help` command that accesses more extensive manpage-like descriptions of
+commands.
+
+* ``git <project> config``
+
+  Configure git-project or any git config sections added by projects.  This will
+  add ``config`` subcommands to plugin commands that manipulate git config
+  sections (e.g. ``git project build config``).
+
+* ``git <project> clone [--worktree]``
+
+  Clone a repository.  Other plugins may hook into this command to provide
+  additional functionality.  With ``--worktree``, set up a worktree environment.
+
+* ``git <project> init [--worktree]``
+
+  Initialize a ``git-project`` config in an existing cloed repository.  With
+  ``--worktree``, setup a worktree environment.
+
+* ``git <project> branch status``
+
+  Report whether local branches are merged to a project branch and whether the
+  local branch head is pushed to a remote.
+
+* ``git <project> branch prune``
+
+  Delete branches that are merged to a project branch and pushed to a remote.
+
+* ``git <project> run <command> [<args>]``
+
+  Run a pre-configured commandm, passing ``<args>`` to it.
+
+* ``git <project> worktree``
+
+  Create and manage worktrees for the project.  This plugin gives ``git
+  <project> clone`` an option to create a special directory layout and a master
+  worktree when performing a bare clone.
+
+  Worktrees can be referenced to set up per-worktree build and install trees
+  such that switching from worktree to worktree does not result in "rebuilding
+  the world."
+
+Worktree environment
+====================
+
+A number of commands can have knowledge of a "worktree environment" with a
+specific layout:
+
+  <path>
+    .git
+    worktree1
+    worktree2
+    worktree3
+
+That is, either a bare clone is done, or an existing clone is converted to a
+bare clone via ``git <project> init --worktree``.  Any conversion will abort if
+the worktree is dirty.  Typically, an ordinary ``git clone`` is followed
+immediately by ``git <project> init --worktree``.
+
+Examples
+========
+
+Initial setup
+-------------
+
+  git clone <url>
+  git <project> init --worktree
+
+Add convenience substitution variables
+--------------------------------------
+
+Adding custom commands
+----------------------
+
+  git <project> run --make-alias configure
+  git <project> run --make-alias build
+  git <project> run --make-alias install
+
+  git <project> add configure debug "cd {builddir} && "
+
+Command Reference
+-----------------
+
+artifact
+--------
+The artifact command adds or removes associations between git config objects
+and file-system objects.
+
+Summary:
+
+  git <project> artifact add <subsection> <path>
+  git <project> artifact rm <subsection> [<path>]
+
+<subsection> is a git config section which will appear under the
+<project>.artifact section.  Artifacts look up objects associated with
+<subsection> and perform substitutions on paths to yield the final
+associated file-system object.  The ``artifact rm`` command simply removes
+an artifact association, it does not remove the artifact itself.  Multiple
+artifact paths may be associated under a single <subsection> and the option
+<path> argument to ``artifact rm`` allows us to remove a single association
+rather than all of them at once.
+
+For example:
+
+  git <project> artifact add worktree.myworktree /path/to/artifact
+
+Presumably, /path/to/artifact is in some way created in association with
+myworktree, for example by the ``run`` command.  When we delete myworktree,
+the artifact association causes /path/to/artifact to also be removed.
+Substitutions can make artifact associations easier to manage:
+
+  git <project> artifact add worktree /path/to/{worktree}/artifact
+
+Notice that we've added the artifact under the more general ``worktree``
+subsection instead of naming a worktree explicitly as before.  Because the
+{worktree} substitution appears in the artifact path, deleting any worktree
+will cause the worktree's name to be substituted into the artifact path,
+forming a unique artifact path to remove.
+
+We may make this even more general:
+
+  git <project> config srcdir "{path}"
+  git <project> config builddir "{srcdir}/build/{worktree}"
+  git <project> config make "make -C {srcdir} BUILDDIR={builddir} {build}"
+  git <project> run --make-alias build
+  git <project> add build debug "{make}"
+  git <project> add build release "{make}"
+  git <project> add build check "{make}"
+  git <project> artifact add worktree "{builddir}"
+
+We've added a single artifact association that will handle any worktree and
+all of our different build types.  When we delete the worktree, all
+artifacts related to debug, release and check builds will also be removed.
+
+The worktree plugin also modifies the clone and init commands, adding a
+--worktree option to both.  With --worktree, clone will create a ``worktree
+layout`` as so:
+
+  clonedir
+    .git
+     master
+
+Here, ``master`` is a worktree created from the master branch.  ``clonedir``
+becames a bare repository, though with refspecs that make it operate like a
+regular clone for fetch and push operations.  That is, the cloned repository
+will still have refs/heads and refs/remotes namespaces.
+
+With --worktree, init will take an existing local clone and convert it to a
+bare repository, removing all checked out files and creating a master
+worktree:
+
+  clonedir
+    .git
+     master
+
+Conversion will abort if the workarea is not in a clean state.  Note that
+all files in clonedir will be deleted so if there are important files not
+part of the underlying repository, the user must take care to preserve them.
+If the workarea hd a branch other than master checked out, no worktree for
+it will be created automatically, though the user may easily create one
+after conversion.
+
+See also:
+
+  clone
+  config
+  init
+  run
+  worktree
+
+branch
+------
+The branch command queries the status of branches against known project
+branches and provides methods to prune old branches.
+
+Summary:
+
+  git <project> branch status [--all] [<refish>]
+  git <project> branch prune [--force] [--no-ask]
+
+The branch status command checks the given <refish> (or all local branches
+with the --all option) against the project-configured branches.  The command
+outputs a table of branches and whether they are merged to a project branch
+and/or pushed to a remote.  For example:
+
+  git <project> config --add branch release
+  git <project> branch status mybranch
+
+The report will show whether mybranch is merged to the release or master
+branches (master is always a configured project branch) and whether the
+commit pointed to mybranch is pushed to a remote.
+
+The branch prune command computes the same information and if the branch is
+merged to a project branch and that project branch is pushed to a remote,
+will ask whether mybranch should be deleted.  If the user indicates yes,
+both the local mybranch and its remote counterpart, if any, will be deleted.
+
+With --force, branches will be pruneed regardless of merge/push status.
+With --no-ask branch prune operates in batch mode, assuming all merged and
+pushed branches should be pruned.
+
+See also:
+
+  config
+
+clone
+-----
+The clone command clones a repository.
+
+Summary:
+
+  git <project> clone <url> [<path>] [--bare]
+
+By itself clone has just the very basic funcionality of the built-in git
+clone command.  Plugins may add options to give the clone command more
+features.  For example, the woktree command adds a --worktree option to have
+clone create a ``worktree layout.``
+
+See also:
+
+  worktree
+
+config
+------
+The config command manages git config settings under the <project> section.
+
+Summary:
+
+  git <project> config [--add] [--unset] <name> [<value>]
+
+The config command operates much like git's built-in config command, except
+all configuration keys are prefixed with <project>, keeping values under a
+single project namespace.  This is a convenient way to store parameters for
+other commands.  For example:
+
+  git <project> config builddir /path/to/build
+  git <project> add run build "make BUILDDIR={builddir} all"
+
+Configuration kays may have their values substituted into other
+configuration values via the {key} specifier.  Special commands like build
+perform the substitution recursively, so configuration vaalues may contain
+substitutions of other configuration values which themselves contain
+substitutions, and so on.  Importantly, substitution only happens when
+commands are run.  Commands should document whether or not they perform
+substitutions.
+
+A git config ``sub-section`` may be substituted with its identifier.  For
+example:
+
+  git <project> worktree add myworktree
+  git <project> config builddir /path/to/{worktree}/build
+
+Here, myworktree is the identifier of a specific worktree sub-section.  If
+myworktree is the currently active worktree (that is, the current directory
+is under the myworktree root), then ``myworktree`` will substitute for
+{woktree}.
+
+See also:
+
+  run
+  worktree
+
+help
+----
+The help command displays tutorial-style help for commands.
+
+Summary:
+
+  git <project> add help [--manpage] <subsection> <text>
+  git <project> help <command>
+
+Users may add help to any project config section.  For example:
+
+  git <project> add help run.build "Perform a build"
+  git <project> add help run.check "Run tests"
+
+All help is stored under a <project>.help config sub-section.  If a command
+supports it, such help may appear in the command's own help output by
+querying the appropriate <project>.help sub-section:
+
+  git <project> run --help
+
+  <standard help text>
+
+  build     -- Perform a build
+  check     -- Run tests
+
+In this way projects can self-document their configurations.  Normally
+<text> is stored in <project>.help.<subsection>.short.  With --manpage,
+<text> is stored in <project>.help.<subsection>.manpage.  Commands may
+reference short help or manpages in various ways to present help.
+
+See also:
+
+  run
+
+init
+----
+The init command initializes project state.
+
+Summary:
+
+  git <project> init
+
+Basic config entries are added to name the project and default branches.
+Plugins may add options to enhance functionality.  For example the worktree
+command adds a --worktree option to convert an existing local clone to a
+``worktree layout.``
+
+See also:
+
+  worktree
+
+run
+---
+The run command executes commands via a shell.
+
+Summary:
+
+  git <project> add run <name> <command>
+  git <project> run --make-alias <name>
+  git <project> run <name>
+
+Full shell substitution is supported, as well as config {key} substitution,
+where the text ``{key}`` is replaced by key's value.
+
+The add run command associates a command string with a name.  The run
+command itself invokes the command string via a shell.  With --make-alias,
+the run comand instead registers an alternative name for ``run.``  For
+example:
+
+  git <project> run --make-alias build
+  git <project> add build all "make -C {path} all"
+  git <project> build all
+
+Note that an alias will prevent ``run`` from invoking the command so in the
+above example we could not invoke the build as such:
+
+  git <project> run all
+
+In this way we may use the same <name> for different registered run aliases,
+which can be convenient:
+
+  git <project> build all
+  git <project> check all
+
+In general any project config {key} will be replaced with its value before
+the command is executed.  Substitution occurs recursively, so if a {key}
+value itself contains a substitution string, it will be replaced as well.
+There are a few special case substitutions.  The {path} key will be replaced
+by the absolute path to the root of the current workarea.  The {branch} key
+will be replaced by the currently-active branch nme.  In addition the {run}
+(or {build}, etc. aliases) will be replaced by their names.  Again, an
+example will make this more clear:
+
+  git <project> config cmd "make -C {path} BLDDIR=/path/to/{build} {build}"
+  git project add build all "{cmd}"
+  git project add build some "{cmd}"
+
+We have configured two different build flavors, each which place build
+results in separate directories and invoke different targets.  Substitution
+proceeds as follows:
+
+  git project build all -> make -C /cur/workarea BLDDIR=/path/to/all all
+  git project build some -> make -C /cur/workarea BLDDIR=/path/to/some some
+
+Some plugins may add scoping rules to the project config, such that a scope
+nested inside the project may override the global project config key value.
+For example the worktree plugin adds a ``worktree`` scope.  The worktree may
+contain key values that override similar keys in the project config.
+
+See also:
+
+  config
+  worktree
+
+worktree
+--------
+The worktree command manages worktrees and connects them to projects.
+
+Summary:
+
+  git <project> worktree add [-b <branch>] <name-or-path> [<committish>]
+  git <project> worktree rm <name-or-path>
+  git <project> worktree config <key> [<value>]
+  git <project> worktree config [--unset] <key> [<value>]
+
+``worktree add`` creates a new git worktree named via <name-or-path> with
+<committish> checked out.  If we pass -b <branch> we'll get a new branch at
+HEAD or <committish> if it is given.  The worktree name is either the given
+name or if name-or-path is a path, the worktree name will be the same as the
+last path component.  If <name-or-path> is a simple name with no directory
+separators, the worktree will be created as a sub-directory of the current
+directory.
+
+To keep things simple, we'll usually always name worktrees similarly (or
+identically) to the branches they reference, though it is not strictly
+necessary to do so.
+
+The key idea behind project worktrees is that they are connected to various
+``artifacts.``  Worktrees are managed together with this artifacts to
+provide a project-level view of various tasks.  For example, a ``run``
+command can create artifacts associated with a worktree.  Removing the
+worktree implicitly removes thee artifacts, making build cleanups easy and
+convenient.  Commands may use the {worktree} substitution to create
+worktree-unique artifacts.  Other substitutions may also referece {worktree}
+in a recursive manner.
+
+Here is a concrete example:
+
+  git <project> config srcdir "{path}"
+  git <project> config builddir "{srcdir}/build/{worktree}"
+  git <project> config make "make -C {srcdir} BUILDDIR={builddir} {build}"
+  git <project> run --make-alias build
+  git <project> add build release "{make}"
+
+Assuming the build system uses BUILDDIR to determine where build artifacts
+go, each worktree will get a unique set of build artifacts, via the
+{builddir} and, recursively., {worktree} substitutions.  When we delete the
+worktree, we'll also delete the associoated build directory.
+
+We associate artifacts with worktrees via the artifact commands.
+
+Another important benefit of worktrees and associated builds is that
+switching to work on a new worktree (by simply editing sources in a
+different worktree directory) will not result in build artifacts from thte
+previous worktree being overwritten.  Thus we avoid the ``rebuild the
+world`` problems of switching branches within the same workarea.  Generally,
+each created branch will have its own worktree and we will rarely, if ever,
+switch branches within a worktree.
+
+A worktree layers a config scope on top of the global project scope, so that
+configuring a key in the worktree with the same name as a key in the project
+will cause the worktree key's value to override the project key's value:
+
+  git <project> config buildwidth 16
+  git <project> worktree config buildwidth 32
+
+If we are in a worktree configured with buildwidth=32, then wherever
+{buildwidth} apeears (say, in a run command), the value 32 will be
+substituted instead of 16.  If we are outside the worktree (for example a
+worktree without a buildwidth configured), then {buildwidth} will be
+substituted with 16.
+
+See also:
+
+  artifact
+  config
+  run

git_project_core_plugins-0.0.23/git_project_core_plugins.egg-info/SOURCES.txt

@@ -0,0 +1,29 @@
+COPYING
+MANIFEST.in
+README.rst
+setup.py
+git_project_core_plugins/__init__.py
+git_project_core_plugins/artifact.py
+git_project_core_plugins/branch.py
+git_project_core_plugins/clone.py
+git_project_core_plugins/common.py
+git_project_core_plugins/config.py
+git_project_core_plugins/help.py
+git_project_core_plugins/init.py
+git_project_core_plugins/run.py
+git_project_core_plugins/worktree.py
+git_project_core_plugins.egg-info/PKG-INFO
+git_project_core_plugins.egg-info/SOURCES.txt
+git_project_core_plugins.egg-info/dependency_links.txt
+git_project_core_plugins.egg-info/entry_points.txt
+git_project_core_plugins.egg-info/not-zip-safe
+git_project_core_plugins.egg-info/requires.txt
+git_project_core_plugins.egg-info/top_level.txt
+tests/test_artifact.py
+tests/test_branch.py
+tests/test_clone.py
+tests/test_config.py
+tests/test_help.py
+tests/test_init.py
+tests/test_run.py
+tests/test_worktree.py

git_project_core_plugins-0.0.23/git_project_core_plugins.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

git_project_core_plugins-0.0.23/git_project_core_plugins.egg-info/entry_points.txt

@@ -0,0 +1,9 @@
+[git_project.plugins]
+artifact = git_project_core_plugins.artifact:ArtifactPlugin
+branch = git_project_core_plugins.branch:BranchPlugin
+clone = git_project_core_plugins.clone:ClonePlugin
+config = git_project_core_plugins.config:ConfigPlugin
+help = git_project_core_plugins.help:HelpPlugin
+init = git_project_core_plugins.init:InitPlugin
+run = git_project_core_plugins.run:RunPlugin
+worktree = git_project_core_plugins.worktree:WorktreePlugin

git_project_core_plugins-0.0.23/git_project_core_plugins.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

git_project_core_plugins-0.0.23/git_project_core_plugins.egg-info/requires.txt

@@ -0,0 +1,3 @@
+git_project>=0.0.17
+progressbar2
+pygit2

git_project_core_plugins-0.0.23/git_project_core_plugins.egg-info/top_level.txt

@@ -0,0 +1 @@
+git_project_core_plugins

{git_project_core_plugins-0.0.21 → git_project_core_plugins-0.0.23}/pyproject.toml

@@ -31,7 +31,7 @@ name = "git-project-core-plugins"
 dynamic = ["dependencies", "readme", "version"]
 description = "The extensible stupid project manager - core functionality"
 license = "AGPL-3.0-or-later"
-requires-python = ">=3"
+requires-python = ">=3.9"
 authors = [
     { name = "David A. Greene", email = "dag@obbligato.org" },
 ]
@@ -95,7 +95,7 @@ cov = [
 ]
 
 [[tool.hatch.envs.all.matrix]]
-python = ["3.7", "3.8", "3.9", "3.10", "3.11"]
+python = ["3.9", "3.10", "3.11"]
 
 [tool.hatch.envs.lint]
 detached = true

{git_project_core_plugins-0.0.21 → git_project_core_plugins-0.0.23}/requirements.txt

@@ -18,5 +18,5 @@
 # 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/>.
 
-git-project >= 0.0.24
-progressbar
+git-project >= 0.0.30
+pytest-console-scripts

{git_project_core_plugins-0.0.21 → git_project_core_plugins-0.0.23}/src/git_project_core_plugins/artifact.py

@@ -137,7 +137,7 @@ class Artifact(SubstitutableConfigObject):
         string: The string on which to perform substitution.
 
         """
-        for path in self.iter_multival('path'):
+        for path in self.iter_multival('itempath'):
             path = self.substitute_value(git, poject, clargs, path)
 
 def command_artifact_add(git, gitproject, project, clargs):
@@ -146,7 +146,7 @@ def command_artifact_add(git, gitproject, project, clargs):
     path = clargs.path
 
     artifact = Artifact.get(git, project.get_section(), ident)
-    artifact.add_item('path', path)
+    artifact.add_item('itempath', path)
 
 def command_artifact_rm(git, gitproject, project, clargs):
     """Implement git-project artifact rm."""
@@ -156,9 +156,9 @@ def command_artifact_rm(git, gitproject, project, clargs):
 
     if hasattr(clargs, 'path') and clargs.path:
         path = clargs.path
-        artifact.rm_item('path', path)
+        artifact.rm_item('itempath', path)
     else:
-        artifact.rm_items('path')
+        artifact.rm_items('itempath')
 
 class ArtifactPlugin(Plugin):
     """
@@ -328,7 +328,7 @@ the final git config section that will hold the artifact path.
                                         self._subsection)
 
             if artifact:
-                for path in artifact.iter_multival('path'):
+                for path in artifact.iter_multival('itempath'):
                     fullpath = artifact.substitute_value(self._git, project, path)
                     run_command_with_shell(f'rm -rf {fullpath}',
                                            show_command=True)

{git_project_core_plugins-0.0.21 → git_project_core_plugins-0.0.23}/src/git_project_core_plugins/branch.py

@@ -131,6 +131,9 @@ def command_branch_prune(git, gitproject, project, clargs):
                  branch_width=branch_width, status_width=status_width))
     print('-' * separator_width)
 
+    # FIXME: Prunes all branchs that start with the given name becuase
+    # iterrefnames does a startswith match.  This is probably not what we should
+    # do.
     for branch in git.iterrefnames([ref]):
         status = 'merged' if project.branch_is_merged(branch) else 'unmerged'