git-project-core-plugins 0.0.26__tar.gz → 0.0.28__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 (53) hide show
  1. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/.gitignore +2 -1
  2. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/MANIFEST.in +2 -1
  3. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/PKG-INFO +170 -130
  4. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/_version.py +2 -2
  5. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/docs/Makefile +2 -1
  6. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/docs/authors.rst +2 -2
  7. git_project_core_plugins-0.0.28/docs/changelog.rst +150 -0
  8. git_project_core_plugins-0.0.28/docs/commands.rst +76 -0
  9. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/docs/conf.py +24 -15
  10. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/docs/index.rst +3 -2
  11. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/docs/intro.rst +2 -2
  12. git_project_core_plugins-0.0.28/docs/license.rst +33 -0
  13. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/docs/make.bat +2 -2
  14. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/hatch_build.py +25 -17
  15. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/pyproject.toml +17 -38
  16. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/requirements.txt +3 -2
  17. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/src/git_project_core_plugins/__init__.py +36 -10
  18. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/src/git_project_core_plugins/_commanddocs.py +9 -8
  19. git_project_core_plugins-0.0.28/src/git_project_core_plugins/artifact.py +392 -0
  20. git_project_core_plugins-0.0.28/src/git_project_core_plugins/branch.py +306 -0
  21. git_project_core_plugins-0.0.28/src/git_project_core_plugins/clone.py +101 -0
  22. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/src/git_project_core_plugins/common.py +4 -2
  23. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/src/git_project_core_plugins/config.py +69 -58
  24. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/src/git_project_core_plugins/help.py +125 -104
  25. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/src/git_project_core_plugins/init.py +26 -22
  26. git_project_core_plugins-0.0.28/src/git_project_core_plugins/run.py +463 -0
  27. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/src/git_project_core_plugins/worktree.py +307 -222
  28. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/tests/common.py +6 -5
  29. git_project_core_plugins-0.0.28/tests/conftest.py +76 -0
  30. git_project_core_plugins-0.0.28/tests/test_artifact.py +414 -0
  31. git_project_core_plugins-0.0.28/tests/test_branch.py +281 -0
  32. git_project_core_plugins-0.0.28/tests/test_clone.py +139 -0
  33. git_project_core_plugins-0.0.28/tests/test_config.py +140 -0
  34. git_project_core_plugins-0.0.28/tests/test_help.py +93 -0
  35. git_project_core_plugins-0.0.28/tests/test_init.py +39 -0
  36. git_project_core_plugins-0.0.28/tests/test_run.py +495 -0
  37. git_project_core_plugins-0.0.28/tests/test_worktree.py +886 -0
  38. git_project_core_plugins-0.0.26/docs/changelog.rst +0 -77
  39. git_project_core_plugins-0.0.26/docs/license.rst +0 -241
  40. git_project_core_plugins-0.0.26/src/git_project_core_plugins/artifact.py +0 -308
  41. git_project_core_plugins-0.0.26/src/git_project_core_plugins/branch.py +0 -238
  42. git_project_core_plugins-0.0.26/src/git_project_core_plugins/clone.py +0 -97
  43. git_project_core_plugins-0.0.26/src/git_project_core_plugins/run.py +0 -441
  44. git_project_core_plugins-0.0.26/tests/conftest.py +0 -82
  45. git_project_core_plugins-0.0.26/tests/test_artifact.py +0 -239
  46. git_project_core_plugins-0.0.26/tests/test_branch.py +0 -244
  47. git_project_core_plugins-0.0.26/tests/test_clone.py +0 -144
  48. git_project_core_plugins-0.0.26/tests/test_config.py +0 -182
  49. git_project_core_plugins-0.0.26/tests/test_help.py +0 -132
  50. git_project_core_plugins-0.0.26/tests/test_init.py +0 -45
  51. git_project_core_plugins-0.0.26/tests/test_run.py +0 -470
  52. git_project_core_plugins-0.0.26/tests/test_worktree.py +0 -833
  53. {git_project_core_plugins-0.0.26 → git_project_core_plugins-0.0.28}/COPYING +0 -0
@@ -13,7 +13,8 @@
13
13
 
14
14
  # This program is distributed in the hope that it will be useful, but WITHOUT
15
15
  # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
16
- # FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
16
+ # FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
17
+ # details.
17
18
 
18
19
  # You should have received a copy of the GNU Affero General Public License along
19
20
  # with git-project. If not, see <https://www.gnu.org/licenses/>.
@@ -13,7 +13,8 @@
13
13
 
14
14
  # This program is distributed in the hope that it will be useful, but WITHOUT
15
15
  # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
16
- # FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
16
+ # FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
17
+ # details.
17
18
 
18
19
  # You should have received a copy of the GNU Affero General Public License along
19
20
  # with git-project. If not, see <https://www.gnu.org/licenses/>.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: git-project-core-plugins
3
- Version: 0.0.26
3
+ Version: 0.0.28
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.38
17
+ Requires-Dist: git-project>=0.0.40
18
18
  Requires-Dist: pytest-console-scripts
19
19
  Provides-Extra: test
20
20
  Requires-Dist: git-project; extra == 'test'
@@ -61,6 +61,7 @@ specific layout::
61
61
 
62
62
  <path>
63
63
  .<name>.git
64
+ .git
64
65
  worktree1
65
66
  worktree2
66
67
  worktree3
@@ -68,8 +69,13 @@ specific layout::
68
69
  That is, either a bare clone is done, or an existing clone is converted to a
69
70
  bare clone via ``git <project> init --worktree``. The bare repository is the
70
71
  hidden ``.<name>.git`` child, named for the last component of the remote url,
71
- and ``<path>`` holds it alongside the worktrees. Any conversion will abort if
72
- the worktree is dirty. Typically, an ordinary ``git clone`` is followed
72
+ and ``<path>`` holds it alongside the worktrees. The ``.git`` beside it is a
73
+ file holding ``gitdir: .<name>.git``, so git works from ``<path>`` too. It is
74
+ a file, not a directory or a symlink, because a go build run from ``<path>``
75
+ fails if ``.git`` resolves to a directory there. A repository that is already
76
+ bare when ``init --worktree`` runs keeps its name and gets no ``.git`` file,
77
+ and its parent directory holds the worktrees. Any conversion will abort if
78
+ the worktree is dirty. Typically, an ordinary ``git clone`` is followed
73
79
  immediately by ``git <project> init --worktree``.
74
80
 
75
81
  Either route also creates a worktree for the project's main branch, so the
@@ -95,14 +101,18 @@ Initial setup
95
101
  Add convenience substitution variables
96
102
  --------------------------------------
97
103
 
98
- Configured values may reference other configured values by name, and
99
- ``{worktree}`` names the active worktree. So a build directory written once
100
- gives every worktree its own::
104
+ Configured values may name other configured values. Inside a worktree,
105
+ ``{path}`` is the worktree's path and ``{worktree}`` is its name. So a build
106
+ directory written once gives every worktree its own::
101
107
 
102
108
  git <project> config srcdir "{path}"
103
109
  git <project> config builddir "{srcdir}/build/{worktree}"
104
110
  git <project> config make "make -C {srcdir} BUILDDIR={builddir} {build}"
105
111
 
112
+ The Substitution and Scopes sections of the git-project documentation
113
+ describe the names, and how a worktree's values override the project's:
114
+ https://pypi.org/project/git-project/
115
+
106
116
  Adding custom commands
107
117
  ----------------------
108
118
 
@@ -112,7 +122,8 @@ Adding custom commands
112
122
  git <project> run --make-alias build
113
123
  git <project> run --make-alias install
114
124
 
115
- git <project> add configure debug "cd {builddir} && "
125
+ git <project> add configure debug "mkdir -p {builddir} && cd {builddir} && cmake -DCMAKE_BUILD_TYPE=Debug {srcdir}"
126
+ git <project> configure debug
116
127
 
117
128
  Command Reference
118
129
  =================
@@ -132,18 +143,26 @@ Summary::
132
143
  <project>.artifact section. Artifacts look up objects associated with
133
144
  <subsection> and perform substitutions on paths to yield the final
134
145
  associated file-system object. The ``artifact rm`` command simply removes
135
- an artifact association, it does not remove the artifact itself. Multiple
136
- artifact paths may be associated under a single <subsection> and the option
137
- <path> argument to ``artifact rm`` allows us to remove a single association
138
- rather than all of them at once.
146
+ an artifact association, it does not remove the artifact itself. A
147
+ <subsection> may hold several paths. With <path>, ``artifact rm`` removes
148
+ only that association. Give <path> as it was added, before substitution.
139
149
 
140
150
  For example::
141
151
 
142
152
  git <project> artifact add worktree.myworktree /path/to/artifact
143
153
 
144
154
  Presumably, /path/to/artifact is in some way created in association with
145
- myworktree, for example by the ``run`` command. When we delete myworktree,
155
+ myworktree, for example by the ``run`` command. When we delete myworktree,
146
156
  the artifact association causes /path/to/artifact to also be removed.
157
+
158
+ Removal runs without a shell. A leading ~ and $VAR references are expanded.
159
+ A path that exists is removed as written. Otherwise it is expanded as a glob,
160
+ and each match is removed. A symbolic link is removed, not its target.
161
+
162
+ Removal refuses the root, the home directory, the current worktree and the
163
+ repository's git directory, and any directory that contains one of them. A
164
+ refused path stops the command before anything is removed.
165
+
147
166
  Substitutions can make artifact associations easier to manage::
148
167
 
149
168
  git <project> artifact add worktree /path/to/{worktree}/artifact
@@ -152,7 +171,9 @@ Notice that we've added the artifact under the more general ``worktree``
152
171
  subsection instead of naming a worktree explicitly as before. Because the
153
172
  {worktree} substitution appears in the artifact path, deleting any worktree
154
173
  will cause the worktree's name to be substituted into the artifact path,
155
- forming a unique artifact path to remove.
174
+ forming a unique artifact path to remove. If a worktree also has its own
175
+ ``worktree.<name>`` artifact, removing that worktree uses only its own, not
176
+ the general one.
156
177
 
157
178
  We may make this even more general::
158
179
 
@@ -178,41 +199,45 @@ See also::
178
199
  branch
179
200
  ------
180
201
 
181
- The branch command queries the status of branches against known project
182
- branches and provides methods to prune old branches.
202
+ The branch command queries the status of branches against the project's
203
+ branches and prunes branches that are finished.
183
204
 
184
205
  Summary::
185
206
 
186
- git <project> branch status [--all] [<refish>]
187
- git <project> branch prune [--force] [--no-ask] [--keep-remote-branch]
207
+ git <project> branch status (--all | --all-user | <pattern>) [<target>]
208
+ git <project> branch prune [--force] [--no-ask] [--keep-remote-branch] (--all-user | <pattern>)
209
+
210
+ A <pattern> matches every branch whose name starts with it, and a name
211
+ without ``refs/`` is looked up under ``refs/heads/``. --all-user matches
212
+ the branches under ``user/<login>``.
188
213
 
189
- The branch status command checks the given <refish> (or all local branches
190
- with the --all option) against the project-configured branches. The command
191
- outputs a table of branches and whether they are merged to a project branch
192
- and/or pushed to a remote. For example::
214
+ branch status prints a table of the matching branches, with whether each
215
+ is merged to a project branch and whether it is pushed to a project
216
+ remote. --all reports on every local branch. With <target>, merged means
217
+ merged to <target> instead. For example::
193
218
 
194
219
  git <project> config --add branch release
195
220
  git <project> branch status mybranch
196
221
 
197
- The report will show whether mybranch is merged to the release or master
198
- branches (master is always a configured project branch) and whether the
199
- commit pointed to mybranch is pushed to a remote.
222
+ The project branch defaults to the repository's main branch, main or
223
+ master, when none is configured. config --add adds more.
200
224
 
201
- The branch prune command computes the same information and if the branch is
202
- merged to a project branch and that project branch is pushed to a remote,
203
- will ask whether mybranch should be deleted. If the user indicates yes,
204
- both the local mybranch and its remote counterpart, if any, will be deleted.
225
+ branch prune asks whether to delete each matching branch that is merged
226
+ to a project branch, locally or on a project remote. If the answer is
227
+ yes, it deletes the local branch and its copy on each project remote.
228
+ A pattern matches project branches too, so check the list before you
229
+ answer.
205
230
 
206
- With --force, branches will be pruned regardless of merge/push status.
207
- With --no-ask branch prune operates in batch mode, assuming all merged and
208
- pushed branches should be pruned. With --keep-remote-branch, only the local
209
- branch is deleted and the remote counterpart is left in place. This is the
210
- same option worktree rm takes, and it matters more here, because branch prune
211
- acts on every branch matching the pattern.
231
+ With --force, branch prune offers every matching branch, merged or not.
232
+ With --no-ask, it deletes without asking. With --keep-remote-branch, it
233
+ deletes only the local branch and leaves the remote copies in place.
234
+ worktree rm takes the same option, and it matters more here, because
235
+ branch prune acts on every branch that matches the pattern.
212
236
 
213
237
  See also::
214
238
 
215
239
  config
240
+ worktree
216
241
 
217
242
  clone
218
243
  -----
@@ -223,10 +248,14 @@ Summary::
223
248
 
224
249
  git <project> clone <url> [<path>] [--bare]
225
250
 
226
- By itself clone has just the very basic functionality of the built-in git
227
- clone command. Plugins may add options to give the clone command more
228
- features. For example, the worktree command adds a --worktree option to
229
- have clone create a ``worktree layout``.
251
+ By itself clone does a basic clone, then sets the project's defaults in
252
+ the new repository. With no <path> it clones into the last component of
253
+ <url> under the current directory, keeping any ``.git`` suffix, where
254
+ ``git clone`` drops it. It offers no ssh key, so an ssh url fails to
255
+ authenticate.
256
+
257
+ Plugins add options to clone. For example, the worktree command adds a
258
+ --worktree option to have clone create a ``worktree layout``.
230
259
 
231
260
  See also::
232
261
 
@@ -249,33 +278,20 @@ other commands. For example::
249
278
  git <project> config builddir /path/to/build
250
279
  git <project> add run build "make BUILDDIR={builddir} all"
251
280
 
252
- Configuration keys may have their values substituted into other
253
- configuration values via the {key} specifier. Special commands like build
254
- perform the substitution recursively, so configuration values may contain
255
- substitutions of other configuration values which themselves contain
256
- substitutions, and so on. Importantly, substitution only happens when
257
- commands are run. Commands should document whether or not they perform
258
- substitutions.
259
-
260
- A git config ``sub-section`` may be substituted with its identifier. For
261
- example::
281
+ A value may name other values as ``{name}``. The commands that use a value,
282
+ such as run, substitute it when they run, not when it is set. For example,
283
+ inside a worktree ``{worktree}`` is that worktree's name::
262
284
 
263
- git <project> worktree add myworktree
264
285
  git <project> config builddir /path/to/{worktree}/build
265
286
 
266
- Here, myworktree is the identifier of a specific worktree sub-section. If
267
- myworktree is the currently active worktree (that is, the current directory
268
- is under the myworktree root), then ``myworktree`` will substitute for
269
- {worktree}.
270
-
271
- The config command also adds a ``config`` subcommand to every plugin
272
- command that manages git config sections, so each one configures its own
273
- section through the same interface::
287
+ The Substitution and Scopes sections of the git-project documentation
288
+ describe the names and how a worktree's values override the project's:
289
+ https://pypi.org/project/git-project/
274
290
 
275
- git <project> build config <name> [<value>]
291
+ The config command also adds a ``config`` subcommand to worktree, which
292
+ sets a value for one worktree and takes that worktree's name first::
276
293
 
277
- A plugin whose sections carry an identifier takes that identifier first,
278
- as ``worktree config`` does.
294
+ git <project> worktree config <ident> <name> [<value>]
279
295
 
280
296
  See also::
281
297
 
@@ -290,9 +306,15 @@ The help command displays tutorial-style help for commands.
290
306
  Summary::
291
307
 
292
308
  git <project> add help [--manpage] <subsection> <text>
293
- git <project> help <command>
309
+ git <project> rm help [--manpage] <subsection>
310
+ git <project> help [<command> | <section>... <name>]
294
311
 
295
- Users may add help to any project config section. For example::
312
+ With no argument, help shows git-project's general help. ``help
313
+ <command>`` shows the command's manual. ``help <section>... <name>``
314
+ shows the manpage stored for that subsection, so ``help run build``
315
+ shows the one stored for ``run.build``.
316
+
317
+ Users may add help to any project config section. For example::
296
318
 
297
319
  git <project> add help run.build "Perform a build"
298
320
  git <project> add help run.check "Run tests"
@@ -305,8 +327,9 @@ querying the appropriate <project>.help sub-section::
305
327
 
306
328
  <standard help text>
307
329
 
308
- build -- Perform a build
309
- check -- Run tests
330
+ Available runs:
331
+ check - Run tests
332
+ build - Perform a build
310
333
 
311
334
  In this way projects can self-document their configurations. Normally
312
335
  <text> is stored in <project>.help.<subsection>.short. With --manpage,
@@ -326,10 +349,13 @@ Summary::
326
349
 
327
350
  git <project> init
328
351
 
329
- Basic config entries are added to name the project and default branches.
330
- Plugins may add options to enhance functionality. For example the worktree
331
- command adds a --worktree option to convert an existing local clone to a
332
- ``worktree layout``.
352
+ init itself changes nothing. Any command run in a repository sets the
353
+ project's ``branch`` to the main branch and its ``remote`` to origin,
354
+ when they are not set already.
355
+
356
+ Plugins add options to init. For example the worktree command adds a
357
+ --worktree option to convert an existing local clone to a ``worktree
358
+ layout``.
333
359
 
334
360
  See also::
335
361
 
@@ -343,91 +369,94 @@ The run command executes commands via a shell.
343
369
  Summary::
344
370
 
345
371
  git <project> add run <name> <command>
372
+ git <project> rm run <name>
346
373
  git <project> run --make-alias <name>
347
- git <project> run <name>
374
+ git <project> run <name> [<option>...]
348
375
 
349
376
  Full shell substitution is supported, as well as config {key} substitution,
350
- where the text ``{key}`` is replaced by key's value.
377
+ where the text ``{key}`` is replaced by key's value. The command is printed
378
+ after substitution. The words given after <name> on the command line are
379
+ shell-quoted, so the shell sees each as one argument and never runs it. In
380
+ those words only a plain {name} is substituted, and other text in braces
381
+ is passed on as it is.
351
382
 
352
- The add run command associates a command string with a name. The run
353
- command itself invokes the command string via a shell. With --make-alias,
354
- the run command instead registers an alternative name for ``run``. For
355
- example::
383
+ The add run command associates a command string with a name, and rm run
384
+ removes it. The run command itself invokes the command string via a shell.
385
+ With --make-alias, run registers a new command, such as ``build``, that
386
+ works like run. For example::
356
387
 
357
388
  git <project> run --make-alias build
358
389
  git <project> add build all "make -C {git_workdir} all"
359
390
  git <project> build all
360
391
 
361
- Note that an alias will prevent ``run`` from invoking the command so in the
362
- above example we could not invoke the build as such::
392
+ Each such command keeps its own list of names. So in the example above
393
+ this fails, because ``all`` was added as a build, not a run::
363
394
 
364
395
  git <project> run all
365
396
 
366
- In this way we may use the same <name> for different registered run aliases,
367
- which can be convenient::
397
+ In this way we may use the same <name> for different commands, which can
398
+ be convenient::
368
399
 
369
400
  git <project> build all
370
401
  git <project> check all
371
402
 
372
- In general any project config {key} will be replaced with its value before
373
- the command is executed. Substitution occurs recursively, so if a {key}
374
- value itself contains a substitution string, it will be replaced as well.
375
- There are a few special case substitutions. The {git_workdir} key will be
376
- replaced by the absolute path to the root of the current workarea. The
377
- {branch} key will be replaced by the currently-active branch name. In
378
- addition the {run} (or {build}, etc. aliases) will be replaced by their
379
- names. Again, an example will make this more clear::
403
+ The Substitution section of the git-project documentation lists the names
404
+ a command may use, such as {git_workdir} and {branch}:
405
+ https://pypi.org/project/git-project/
406
+
407
+ The run command adds its own. {run}, or the alias name such as {build},
408
+ gives the name of the command being run. An example will make this more
409
+ clear::
380
410
 
381
411
  git <project> config cmd "make -C {git_workdir} BLDDIR=/path/to/{build} {build}"
382
- git project add build all "{cmd}"
383
- git project add build some "{cmd}"
412
+ git <project> add build all "{cmd}"
413
+ git <project> add build some "{cmd}"
384
414
 
385
415
  We have configured two different build flavors, each which place build
386
416
  results in separate directories and invoke different targets. Substitution
387
417
  proceeds as follows::
388
418
 
389
- git project build all -> make -C /cur/workarea BLDDIR=/path/to/all all
390
- git project build some -> make -C /cur/workarea BLDDIR=/path/to/some some
419
+ git <project> build all -> make -C /cur/workarea BLDDIR=/path/to/all all
420
+ git <project> build some -> make -C /cur/workarea BLDDIR=/path/to/some some
391
421
 
392
422
  Extra options passed to the run command may be referenced in the command
393
423
  string::
394
424
 
395
- git project add build extra "echo {options}"
396
- git project build extra hello world! -> echo hello world!
425
+ git <project> add build extra "echo {options}"
426
+ git <project> build extra hello world! -> echo hello world!
397
427
 
398
428
  Individual options may also be referenced::
399
429
 
400
- git project add build extra "echo {options_1} {options_0}"
401
- git project build extra hello world! -> echo world! hello
430
+ git <project> add build extra "echo {options_1} {options_0}"
431
+ git <project> build extra hello world! -> echo world! hello
402
432
 
403
433
  A special dash-separated "key" string composed of option values may be
404
434
  generated::
405
435
 
406
- git project add build any "make {option_key}"
407
- git project build any target debug -> make target-debug
436
+ git <project> add build any "make {option_key}"
437
+ git <project> build any target debug -> make target-debug
408
438
 
409
439
  A special {option_keysep} substitution will result in a - if there are
410
440
  options and the empty string otherwise::
411
441
 
412
- git project add build any "make my{option_keysep}{option_key}"
413
- git project build any target debug -> make my-target-debug
414
- git project build any -> make my
442
+ git <project> add build any "make my{option_keysep}{option_key}"
443
+ git <project> build any target debug -> make my-target-debug
444
+ git <project> build any -> make my
415
445
 
416
446
  Other substitutions may be used in options::
417
447
 
418
- git project add build branch "make {options}"
419
- git project build branch {branch} -> make dev # On the dev branch
448
+ git <project> add build branch "make {options}"
449
+ git <project> build branch {branch} -> make dev # On the dev branch
420
450
 
421
- A special substitution {option_names} is a space-separated list of option
422
- values with no additional substitutions::
451
+ A special substitution {option_names} gives the options separated by
452
+ spaces, with their braces removed, so they are not substituted::
423
453
 
424
- git project add build branch "make {option_names} {options}"
425
- git project build branch {branch} -> make branch dev # On the dev branch
454
+ git <project> add build branch "make {option_names} {options}"
455
+ git <project> build branch {branch} -> make branch dev # On the dev branch
426
456
 
427
- Some plugins may add scoping rules to the project config, such that a scope
428
- nested inside the project may override the global project config key value.
429
- For example the worktree plugin adds a ``worktree`` scope. The worktree may
430
- contain key values that override similar keys in the project config.
457
+ Inside a worktree, a value set for that worktree overrides the project's
458
+ value of the same name. See the Scopes section of the git-project
459
+ documentation.
431
460
 
432
461
  See also::
433
462
 
@@ -443,24 +472,33 @@ Summary::
443
472
 
444
473
  git <project> worktree add [-b <branch>] <name-or-path> [<committish>]
445
474
  git <project> worktree rm [-f] [--keep-branch] [--keep-remote-branch]
446
- <name-or-path>
475
+ <name>
447
476
  git <project> worktree config <ident> [--add] [--unset] <name> [<value>]
448
477
 
449
- ``worktree add`` creates a new git worktree named via <name-or-path> with
450
- <committish> checked out. If we pass -b <branch> we'll get a new branch at
451
- HEAD or <committish> if it is given. The worktree name is either the given
452
- name or if name-or-path is a path, the worktree name will be the same as the
453
- last path component. If <name-or-path> is a simple name with no directory
454
- separators, the worktree will be created as a sub-directory of the current
455
- directory.
478
+ ``worktree add`` creates a worktree at <name-or-path> and checks out a
479
+ branch in it. The worktree's name is the last component of <name-or-path>.
480
+ The branch is named after <name-or-path>: a simple name gives a branch of
481
+ that name, and a relative path such as ``../user/topic`` gives
482
+ ``user/topic``, the part after any ``..``. That branch is created at
483
+ <committish>, or at HEAD, when it does not exist yet. An existing branch is
484
+ checked out as it is, and <committish> is then ignored. With -b <branch>,
485
+ the new branch <branch> is created at <committish> or HEAD and checked out
486
+ instead.
487
+
488
+ A relative path that does not start with ``..`` is placed under the root of
489
+ the current worktree, or under the current directory in a bare repository.
490
+ A path that starts with ``..`` is taken from the current directory. So
491
+ ``worktree add ../topic``, run in the main worktree, puts the new worktree
492
+ beside it, and ``worktree add topic`` puts it inside.
456
493
 
457
494
  To keep things simple, we'll usually always name worktrees similarly (or
458
495
  identically) to the branches they reference, though it is not strictly
459
496
  necessary to do so.
460
497
 
461
- ``worktree rm`` removes a worktree, along with its workarea and its
462
- associated build and install trees. The branch is deleted too, locally and
463
- on every remote, unless a flag says otherwise: ``--keep-branch`` leaves the
498
+ ``worktree rm`` removes a worktree and its workarea. It first removes the
499
+ paths that ``artifact`` associates with the worktree, and if one of those is
500
+ refused, nothing is removed. The branch is deleted too, locally and on each
501
+ project remote, unless a flag says otherwise: ``--keep-branch`` leaves the
464
502
  branch alone everywhere, and ``--keep-remote-branch`` deletes only the
465
503
  local copy. A branch the project configures is never deleted, whatever the
466
504
  flags say. Removing a worktree whose branch is unmerged requires ``-f``,
@@ -508,11 +546,11 @@ will cause the worktree key's value to override the project key's value::
508
546
  The worktree to configure is named explicitly, so myworktree gets
509
547
  buildwidth=32 while the project keeps 16.
510
548
 
511
- If we are in a worktree configured with buildwidth=32, then wherever
512
- {buildwidth} appears (say, in a run command), the value 32 will be
513
- substituted instead of 16. If we are outside the worktree (for example a
514
- worktree without a buildwidth configured), then {buildwidth} will be
515
- substituted with 16.
549
+ Inside myworktree, wherever {buildwidth} appears (say, in a run command),
550
+ 32 is substituted instead of 16. Outside myworktree, or in a worktree with
551
+ no buildwidth of its own, {buildwidth} gives 16. The Scopes section of the
552
+ git-project documentation describes the rule:
553
+ https://pypi.org/project/git-project/
516
554
 
517
555
  The worktree plugin also adds a --worktree option to the clone and init
518
556
  commands. Both set up the ``worktree layout`` described in the package
@@ -523,8 +561,10 @@ top-level directory holds it alongside the worktrees.
523
561
  ``clone --worktree`` clones bare, then rewrites the fetch refspec and sets
524
562
  the main branch to track its remote branch, so fetch and pull behave as
525
563
  they do in a regular clone. The refs/heads and refs/remotes namespaces
526
- remain, and every other local branch is deleted. Add ``--bare`` to skip
527
- that rewrite and keep a plain bare clone.
564
+ remain, and every other local branch is deleted. Add ``--bare`` to skip
565
+ the refspec rewrite. The clone still gets the ``.git`` file and the main
566
+ worktree. With no <path>, ``clone --worktree`` uses the current directory
567
+ itself as the top-level directory, where a plain clone makes a new one.
528
568
 
529
569
  ``init --worktree`` converts an existing clone in place. The workarea must
530
570
  be clean. The conversion deletes every file in the top-level directory
@@ -564,8 +604,8 @@ See also::
564
604
  ..
565
605
  This program is distributed in the hope that it will be useful, but WITHOUT
566
606
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
567
- FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
568
- more details.
607
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
608
+ for more details.
569
609
 
570
610
  ..
571
611
  You should have received a copy of the GNU Affero General Public License
@@ -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.26'
22
- __version_tuple__ = version_tuple = (0, 0, 26)
21
+ __version__ = version = '0.0.28'
22
+ __version_tuple__ = version_tuple = (0, 0, 28)
23
23
 
24
24
  __commit_id__ = commit_id = None
@@ -13,7 +13,8 @@
13
13
 
14
14
  # This program is distributed in the hope that it will be useful, but WITHOUT
15
15
  # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
16
- # FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
16
+ # FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
17
+ # details.
17
18
 
18
19
  # You should have received a copy of the GNU Affero General Public License along
19
20
  # with dartt. If not, see <https://www.gnu.org/licenses/>.
@@ -19,8 +19,8 @@
19
19
  ..
20
20
  This program is distributed in the hope that it will be useful, but WITHOUT
21
21
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
22
- FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
23
- more details.
22
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
23
+ for more details.
24
24
 
25
25
  ..
26
26
  You should have received a copy of the GNU Affero General Public License