git-project-core-plugins 0.0.32__tar.gz → 0.0.33__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/PKG-INFO +188 -4
  2. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/_version.py +2 -2
  3. git_project_core_plugins-0.0.33/changelog.d/README.rst +35 -0
  4. git_project_core_plugins-0.0.33/changelog.py +531 -0
  5. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/docs/changelog.rst +32 -1
  6. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/docs/commands.rst +10 -0
  7. git_project_core_plugins-0.0.33/docs/contributing.rst +83 -0
  8. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/docs/index.rst +1 -0
  9. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/pyproject.toml +2 -0
  10. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/requirements.txt +1 -1
  11. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/src/git_project_core_plugins/__init__.py +4 -0
  12. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/src/git_project_core_plugins/artifact.py +72 -49
  13. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/src/git_project_core_plugins/common.py +35 -0
  14. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/src/git_project_core_plugins/help.py +3 -1
  15. git_project_core_plugins-0.0.33/src/git_project_core_plugins/multirepo.py +1409 -0
  16. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/src/git_project_core_plugins/run.py +3 -1
  17. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/src/git_project_core_plugins/worktree.py +377 -62
  18. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/tests/test_artifact.py +81 -0
  19. git_project_core_plugins-0.0.33/tests/test_changelog.py +759 -0
  20. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/tests/test_help.py +18 -0
  21. git_project_core_plugins-0.0.33/tests/test_multirepo.py +1712 -0
  22. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/tests/test_run.py +20 -0
  23. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/tests/test_worktree.py +350 -0
  24. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/.gitignore +0 -0
  25. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/COPYING +0 -0
  26. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/MANIFEST.in +0 -0
  27. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/docs/Makefile +0 -0
  28. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/docs/authors.rst +0 -0
  29. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/docs/conf.py +0 -0
  30. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/docs/intro.rst +0 -0
  31. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/docs/license.rst +0 -0
  32. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/docs/make.bat +0 -0
  33. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/hatch_build.py +0 -0
  34. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/src/git_project_core_plugins/_commanddocs.py +0 -0
  35. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/src/git_project_core_plugins/branch.py +0 -0
  36. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/src/git_project_core_plugins/clone.py +0 -0
  37. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/src/git_project_core_plugins/config.py +0 -0
  38. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/src/git_project_core_plugins/init.py +0 -0
  39. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/tests/common.py +0 -0
  40. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/tests/conftest.py +0 -0
  41. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/tests/test_branch.py +0 -0
  42. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/tests/test_clone.py +0 -0
  43. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/tests/test_config.py +0 -0
  44. {git_project_core_plugins-0.0.32 → git_project_core_plugins-0.0.33}/tests/test_init.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: git-project-core-plugins
3
- Version: 0.0.32
3
+ Version: 0.0.33
4
4
  Summary: The extensible stupid project manager - core functionality
5
5
  Author-email: "David A. Greene" <dag@obbligato.org>
6
6
  License-Expression: AGPL-3.0-or-later
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3.10
14
14
  Classifier: Programming Language :: Python :: 3.11
15
15
  Classifier: Topic :: Software Development :: Version Control :: Git
16
16
  Requires-Python: >=3.10
17
- Requires-Dist: git-project>=0.0.43
17
+ Requires-Dist: git-project>=0.0.44
18
18
  Requires-Dist: pytest-console-scripts
19
19
  Provides-Extra: test
20
20
  Requires-Dist: git-project; extra == 'test'
@@ -40,6 +40,7 @@ git repositories. These plugins include commands to:
40
40
  #. Run commands (e.g. configure/build/install)
41
41
  #. Associate artifacts with a project
42
42
  #. Show extended help for a command
43
+ #. Run a command in every repository of a set
43
44
 
44
45
  These plugins add a number of commands to git-project. Each command has an
45
46
  associated ``--help`` option to describe its function and options. There is
@@ -366,6 +367,91 @@ See also::
366
367
 
367
368
  worktree
368
369
 
370
+ multirepo
371
+ ---------
372
+
373
+ The multirepo command runs one command in every repository of a set.
374
+
375
+ Summary::
376
+
377
+ git <project> multirepo [-j <n>] [--skip-missing]
378
+ [--commit <member> <sha>]
379
+ <set> <command> [<arg>...]
380
+
381
+ ``mr`` and ``multi`` are aliases for ``multirepo``. The ``set`` command
382
+ defines the sets. For each member of <set>, in the order the set lists
383
+ them, multirepo runs ``git <project> <command> <arg>...`` as a separate
384
+ process, in the member's umbrella. The commands it runs are ``worktree
385
+ add``, ``worktree rm``, ``worktree config``, ``branch status``, ``branch
386
+ prune``, ``config`` and ``run``. It refuses any other command before
387
+ anything runs.
388
+
389
+ Before anything runs, the root of every member must be an umbrella whose
390
+ ``origin`` url is the member's url, ignoring one trailing ``/`` and one
391
+ trailing ``.git``. A member whose root does not exist stops the command,
392
+ unless ``--skip-missing`` is given, which skips the member with a notice.
393
+ A root that exists and is anything else always stops it. multirepo also
394
+ refuses to run while GIT_DIR or a variable like it is set, since each of
395
+ them points git somewhere other than the member's umbrella.
396
+
397
+ For ``worktree add`` and ``worktree rm``, multirepo first runs the
398
+ command with ``--check`` in every member. When any check fails, it
399
+ prints each failure and runs nothing. Before that, ``worktree add`` is
400
+ refused when two members would add a worktree at the same path, as
401
+ ``../<name>`` does in umbrellas that share a directory. multirepo also
402
+ passes ``--multirepo <set>`` to both commands. ``worktree add`` records <set> in the new
403
+ worktree, and ``worktree rm`` refuses a worktree that was not added for
404
+ <set>, so a worktree of the same name in another repository is left
405
+ alone. In that removal a member keeps its branch unless the add created
406
+ it. The <arg>s may not hold ``--check`` or ``--multirepo`` in any form.
407
+
408
+ Every member runs, even after one fails, and nothing is rolled back. At
409
+ the end a table gives each member's result. For a successful ``worktree
410
+ add`` it gives the ``worktree rm`` that undoes it. For a failed one it
411
+ says which of the branch, the record, the worktree and its path exist.
412
+ The exit status is non-zero when any member failed.
413
+
414
+ The members run one at a time by default, attached to the terminal,
415
+ each after a ``== <member>`` line. ``-j <n>`` runs up to <n> of them at
416
+ once, from 1 to 16. They get no standard input, and each one's output is
417
+ printed under its ``== <member>`` line when it finishes. ``-j`` is refused for ``run``, and for
418
+ ``branch prune`` without ``--no-ask``, since either may ask a question.
419
+
420
+ A Ctrl-C reaches the running member directly. multirepo then starts no
421
+ more members, prints the table and exits with a failure status. SIGTERM
422
+ does the same, and multirepo also sends SIGTERM to the running member,
423
+ then SIGKILL if it has not exited after five seconds. SIGHUP is treated
424
+ as SIGTERM. With ``-j``, any of these signals makes multirepo send
425
+ SIGTERM to the process group of each running member, then SIGKILL to any
426
+ group left after five seconds.
427
+
428
+ ``--commit <member> <sha>`` lines the new worktrees up in time. It works
429
+ only with ``worktree add`` and no <committish>. In <member> the new
430
+ branch starts at <sha>. In each other member it starts at the first
431
+ commit, following first parents back from the branch a plain ``worktree
432
+ add`` would start from, whose author date is at or before <sha>'s.
433
+ multirepo prints each member's commit. It refuses when <member> is not
434
+ in <set> or was skipped, when any member has no such commit, and when the
435
+ worktree's branch already exists at another commit, since ``worktree
436
+ add`` would use that branch as it is.
437
+
438
+ For example::
439
+
440
+ git <project> set add tools git-project \
441
+ --url https://github.com/greened/git-project.git \
442
+ --root ~/projects/git-project
443
+ git <project> set add tools git-project-core-plugins \
444
+ --url https://github.com/greened/git-project-core-plugins.git \
445
+ --root ~/projects/git-project-core-plugins
446
+ git <project> set clone tools
447
+ git <project> multirepo tools worktree add topic
448
+ git <project> mr tools worktree rm topic
449
+
450
+ See also::
451
+
452
+ set
453
+ worktree
454
+
369
455
  run
370
456
  ---
371
457
 
@@ -468,6 +554,87 @@ See also::
468
554
  config
469
555
  worktree
470
556
 
557
+ set
558
+ ---
559
+
560
+ The set command manages the sets of repositories that ``multirepo`` runs
561
+ in.
562
+
563
+ Summary::
564
+
565
+ git <project> set list [<set>]
566
+ git <project> set add <set> <member> [--url <url> --root <root>]
567
+ git <project> set rm <set> <member>
568
+ git <project> set clone <set>
569
+
570
+ The sets live in a file of their own, in git config syntax, outside any
571
+ repository, so a dotfiles repository can carry them between machines.
572
+ ``<project>.set.file`` in the global git config names the file. It must
573
+ have exactly one value, an absolute path that may start with ``~``, and
574
+ the file must exist. The global config is the file GIT_CONFIG_GLOBAL
575
+ names when that is set, and otherwise ``~/.gitconfig`` and the XDG
576
+ ``git/config``. The sets are read from the set file alone, so the
577
+ file may be included in the global config, but need not be. For
578
+ ``git dev``::
579
+
580
+ git config --global dev.set.file ~/dotfiles/git-sets
581
+ touch ~/dotfiles/git-sets
582
+
583
+ The set file holds two kinds of section. A member is a repository,
584
+ defined once, and any number of sets may list it. A set runs its members
585
+ in the order it lists them::
586
+
587
+ [dev "repo.git-project"]
588
+ url = https://github.com/greened/git-project.git
589
+ root = ~/projects/git-project
590
+ [dev "set.tools"]
591
+ repo = git-project
592
+ repo = git-project-core-plugins
593
+
594
+ Set and member names are 1 to 64 letters, digits, ``_`` and ``-``, and
595
+ start with a letter or digit. Each command checks the whole file before
596
+ it does anything. It refuses a key not shown above, a member without
597
+ exactly one url and one root, two members with the same root, a root
598
+ that does not start with ``~/`` or that leaves the home directory, a url
599
+ that is a relative path, and a set that lists a member twice or one that
600
+ is not defined. It accepts ``<project>.set.file`` too, which the set
601
+ file may hold when the global config includes it. A url is an absolute
602
+ path, ``<scheme>://...`` or ``<host>:<path>``.
603
+
604
+ ``set list`` prints each set, or only <set>, with each member's root and
605
+ its state: ``ok`` for an umbrella cloned from the member's url,
606
+ ``missing`` when the root does not exist, and otherwise why it is
607
+ invalid.
608
+
609
+ ``set add`` adds <member> to the end of <set>, making the set if needed.
610
+ With ``--url`` and ``--root`` it also defines the member. A member that
611
+ is already defined must be given its own url and root, or neither, so a
612
+ member that other sets list never changes under them. To change a
613
+ definition, edit the file. ``set rm`` removes <member> from <set> and
614
+ keeps its definition. Removing a set's last member removes the set.
615
+
616
+ ``set add`` and ``set rm`` lock ``<file>.multirepo-lock``, which they
617
+ leave in place beside the set file, so two of them never lose each
618
+ other's change. Each edits a copy of the file, checks it and then moves
619
+ it over the file, so a failure leaves the file as it was. A symlink to
620
+ the set file stays a symlink.
621
+
622
+ ``set clone`` clones each member whose root does not exist, as ``clone
623
+ --worktree <url> <root>`` does, one at a time. Like ``clone``, it offers
624
+ no ssh key, so give a member it must clone an https url. A member whose
625
+ root is already an umbrella cloned from its url is left alone. A root
626
+ that exists and is anything else stops the command before anything is
627
+ cloned, so a clone that failed partway is never taken for a finished
628
+ one. A failed clone does not stop the rest. Ctrl-C, SIGTERM and SIGHUP
629
+ work as they do for ``multirepo`` without ``-j``. At the end a table
630
+ gives each member's result, and the exit status is non-zero when any
631
+ clone failed.
632
+
633
+ See also::
634
+
635
+ clone
636
+ multirepo
637
+
471
638
  worktree
472
639
  --------
473
640
 
@@ -475,9 +642,10 @@ The worktree command manages worktrees and connects them to projects.
475
642
 
476
643
  Summary::
477
644
 
478
- git <project> worktree add [-b <branch>] <name-or-path> [<committish>]
645
+ git <project> worktree add [-b <branch>] [--check] [--multirepo <set>]
646
+ <name-or-path> [<committish>]
479
647
  git <project> worktree rm [-f] [--keep-branch] [--keep-remote-branch]
480
- <name>
648
+ [--check] [--multirepo <set>] <name>
481
649
  git <project> worktree config <ident> [--add] [--unset] <name> [<value>]
482
650
  git <project> worktree migrate [--apply]
483
651
 
@@ -500,6 +668,14 @@ directory. So ``worktree add ../topic``, run in the main worktree of a
500
668
  plain clone, puts the new worktree beside it, and ``worktree add topic``
501
669
  puts it inside.
502
670
 
671
+ ``worktree add`` refuses, before it changes anything, when the path
672
+ exists, when git or git-project already has a worktree of that name, when
673
+ the branch it would create exists or is not a valid name, and when the
674
+ branch it would check out is checked out in another worktree. It creates
675
+ the branch, then the worktree, then the worktree's record. When a step
676
+ fails it removes what the earlier steps made. The record gets
677
+ ``branchcreated = true`` when the add created the branch.
678
+
503
679
  To keep things simple, we'll usually always name worktrees similarly (or
504
680
  identically) to the branches they reference, though it is not strictly
505
681
  necessary to do so.
@@ -513,6 +689,14 @@ local copy. A branch the project configures is never deleted, whatever the
513
689
  flags say. Removing a worktree whose branch is unmerged requires ``-f``,
514
690
  unless ``--keep-branch`` means the branch survives anyway.
515
691
 
692
+ With ``--check``, ``worktree add`` and ``worktree rm`` make the checks
693
+ they would make before changing anything, report the result and change
694
+ nothing. ``--multirepo <set>`` ties the worktree to multirepo set <set>.
695
+ ``worktree add`` writes ``multirepo = <set>`` into the new worktree's
696
+ record. ``worktree rm`` then refuses a worktree whose record does not
697
+ name <set>, and keeps the branch unless the record has ``branchcreated =
698
+ true``. It refuses a record whose ``branchcreated`` is anything else.
699
+
516
700
  The key idea behind project worktrees is that they are connected to various
517
701
  ``artifacts``. Worktrees are managed together with these artifacts to
518
702
  provide a project-level view of various tasks. For example, a ``run``
@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
18
18
  commit_id: str | None
19
19
  __commit_id__: str | None
20
20
 
21
- __version__ = version = '0.0.32'
22
- __version_tuple__ = version_tuple = (0, 0, 32)
21
+ __version__ = version = '0.0.33'
22
+ __version_tuple__ = version_tuple = (0, 0, 33)
23
23
 
24
24
  __commit_id__ = commit_id = None
@@ -0,0 +1,35 @@
1
+ ..
2
+ SPDX-FileCopyrightText: 2026-present David A. Greene <dag@obbligato.org>
3
+
4
+ ..
5
+ SPDX-License-Identifier: AGPL-3.0-or-later
6
+
7
+ ..
8
+ Copyright 2026 David A. Greene
9
+
10
+ ..
11
+ This file is part of git-project
12
+
13
+ ..
14
+ git-project is free software: you can redistribute it and/or modify it under
15
+ the terms of the GNU Affero General Public License as published by the Free
16
+ Software Foundation, either version 3 of the License, or (at your option)
17
+ any later version.
18
+
19
+ ..
20
+ This program is distributed in the hope that it will be useful, but WITHOUT
21
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
22
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
23
+ for more details.
24
+
25
+ ..
26
+ You should have received a copy of the GNU Affero General Public License
27
+ along with git-project. If not, see <https://www.gnu.org/licenses/>.
28
+
29
+ Each file here other than this one is one entry for the next release's
30
+ changelog, named ``<slug>.<category>.rst``, where the category is
31
+ ``added``, ``changed``, ``deprecated``, ``removed``, ``fixed`` or
32
+ ``security``. An entry is plain RST with no Sphinx roles, and a link
33
+ takes the anonymous inline form ```text <URL>`__``. At a release, ``changelog.py``
34
+ moves the entries into ``docs/changelog.rst`` and removes their files.
35
+ See the Changelog section of ``docs/contributing.rst``.