git-well 0.3.1__tar.gz → 0.3.3__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 (73) hide show
  1. {git_well-0.3.1 → git_well-0.3.3}/PKG-INFO +2 -2
  2. git_well-0.3.3/README.rst +680 -0
  3. {git_well-0.3.1 → git_well-0.3.3}/git_well/__init__.py +1 -1
  4. git_well-0.3.3/git_well/_utils.py +380 -0
  5. git_well-0.3.3/git_well/archive_source/__init__.py +20 -0
  6. git_well-0.3.3/git_well/archive_source/_common.py +117 -0
  7. git_well-0.3.3/git_well/archive_source/_io.py +443 -0
  8. git_well-0.3.3/git_well/archive_source/_policy.py +501 -0
  9. git_well-0.3.3/git_well/archive_source/_prune.py +620 -0
  10. git_well-0.3.3/git_well/archive_source/_repo.py +1007 -0
  11. git_well-0.3.3/git_well/archive_source/api.py +902 -0
  12. git_well-0.3.3/git_well/archive_source/patch.py +1249 -0
  13. git_well-0.3.3/git_well/archive_source/patch_apply.py +737 -0
  14. git_well-0.3.3/git_well/epoch/__init__.py +99 -0
  15. git_well-0.3.3/git_well/epoch/core.py +4499 -0
  16. git_well-0.3.3/git_well/epoch/locator.py +495 -0
  17. git_well-0.3.3/git_well/epoch/sandbox.py +1063 -0
  18. git_well-0.3.3/git_well/epoch/stats.py +329 -0
  19. git_well-0.3.3/git_well/git_archive_source.py +244 -0
  20. {git_well-0.3.1 → git_well-0.3.3}/git_well/git_autoconf_gpgsign.py +20 -11
  21. {git_well-0.3.1 → git_well-0.3.3}/git_well/git_branch_cleanup.py +18 -15
  22. {git_well-0.3.1 → git_well-0.3.3}/git_well/git_branch_upgrade.py +16 -14
  23. {git_well-0.3.1 → git_well-0.3.3}/git_well/git_discover_remote.py +22 -18
  24. git_well-0.3.3/git_well/git_epoch.py +774 -0
  25. git_well-0.3.3/git_well/git_rebase_add_continue.py +203 -0
  26. {git_well-0.3.1 → git_well-0.3.3}/git_well/git_remote_protocol.py +95 -56
  27. {git_well-0.3.1 → git_well-0.3.3}/git_well/git_squash.py +20 -14
  28. {git_well-0.3.1 → git_well-0.3.3}/git_well/git_squash_streaks.py +39 -32
  29. {git_well-0.3.1 → git_well-0.3.3}/git_well/git_stats.py +5 -3
  30. git_well-0.3.3/git_well/git_sync.py +349 -0
  31. {git_well-0.3.1 → git_well-0.3.3}/git_well/git_track_upstream.py +9 -6
  32. {git_well-0.3.1 → git_well-0.3.3}/git_well/git_url_components.py +14 -7
  33. git_well-0.3.3/git_well/ipfs.py +1161 -0
  34. {git_well-0.3.1 → git_well-0.3.3}/git_well/main.py +14 -2
  35. {git_well-0.3.1 → git_well-0.3.3}/git_well/patchdir/git_patchdir_apply.py +14 -8
  36. {git_well-0.3.1 → git_well-0.3.3}/git_well/patchdir/git_patchdir_save.py +5 -5
  37. {git_well-0.3.1 → git_well-0.3.3}/git_well/patchdir/patchdir_modal.py +2 -2
  38. {git_well-0.3.1 → git_well-0.3.3}/git_well/repo.py +12 -12
  39. {git_well-0.3.1 → git_well-0.3.3}/git_well.egg-info/PKG-INFO +2 -2
  40. {git_well-0.3.1 → git_well-0.3.3}/git_well.egg-info/SOURCES.txt +22 -0
  41. {git_well-0.3.1 → git_well-0.3.3}/git_well.egg-info/entry_points.txt +1 -0
  42. {git_well-0.3.1 → git_well-0.3.3}/git_well.egg-info/requires.txt +2 -2
  43. {git_well-0.3.1 → git_well-0.3.3}/pyproject.toml +3 -1
  44. {git_well-0.3.1 → git_well-0.3.3}/requirements/runtime.txt +1 -1
  45. git_well-0.3.3/tests/test_archive_source_branches.py +294 -0
  46. git_well-0.3.3/tests/test_archive_source_checkout_revision.py +132 -0
  47. git_well-0.3.3/tests/test_archive_source_ref_patches.py +289 -0
  48. git_well-0.3.3/tests/test_archive_source_windows_cleanup.py +191 -0
  49. git_well-0.3.3/tests/test_bugfixes.py +284 -0
  50. git_well-0.3.3/tests/test_cli.py +3419 -0
  51. git_well-0.3.3/tests/test_git_epoch.py +1940 -0
  52. git_well-0.3.3/tests/test_git_portability.py +50 -0
  53. git_well-0.3.3/tests/test_ipfs.py +337 -0
  54. git_well-0.3.1/README.rst +0 -283
  55. git_well-0.3.1/git_well/_utils.py +0 -317
  56. git_well-0.3.1/git_well/git_archive_source.py +0 -774
  57. git_well-0.3.1/git_well/git_rebase_add_continue.py +0 -248
  58. git_well-0.3.1/git_well/git_sync.py +0 -345
  59. git_well-0.3.1/git_well/ipfs.py +0 -1283
  60. git_well-0.3.1/tests/test_cli.py +0 -164
  61. git_well-0.3.1/tests/test_ipfs.py +0 -333
  62. {git_well-0.3.1 → git_well-0.3.3}/MANIFEST.in +0 -0
  63. {git_well-0.3.1 → git_well-0.3.3}/git_well/__main__.py +0 -0
  64. {git_well-0.3.1 → git_well-0.3.3}/git_well/demo/__init__.py +0 -0
  65. {git_well-0.3.1 → git_well-0.3.3}/git_well/patchdir/__init__.py +0 -0
  66. {git_well-0.3.1 → git_well-0.3.3}/git_well/py.typed +0 -0
  67. {git_well-0.3.1 → git_well-0.3.3}/git_well.egg-info/dependency_links.txt +0 -0
  68. {git_well-0.3.1 → git_well-0.3.3}/git_well.egg-info/top_level.txt +0 -0
  69. {git_well-0.3.1 → git_well-0.3.3}/requirements/docs.txt +0 -0
  70. {git_well-0.3.1 → git_well-0.3.3}/requirements/optional.txt +0 -0
  71. {git_well-0.3.1 → git_well-0.3.3}/requirements/tests.txt +0 -0
  72. {git_well-0.3.1 → git_well-0.3.3}/setup.cfg +0 -0
  73. {git_well-0.3.1 → git_well-0.3.3}/tests/test_import.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: git_well
3
- Version: 0.3.1
3
+ Version: 0.3.3
4
4
  Summary: The git_well module
5
5
  Author-email: Jon Crall <erotemic@gmail.com>
6
6
  License: Apache 2
@@ -16,7 +16,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
16
16
  Classifier: Topic :: Utilities
17
17
  Requires-Python: >=3.10
18
18
  Requires-Dist: ubelt>=1.3.3
19
- Requires-Dist: scriptconfig>=0.9.1; python_version >= "3.6"
19
+ Requires-Dist: kwconf>=0.12.0; python_version >= "3.10"
20
20
  Requires-Dist: rich>=12.4.4; python_version >= "3.8"
21
21
  Requires-Dist: rich>=11.2.0; python_version < "3.8" and python_version >= "3.6"
22
22
  Requires-Dist: git-python>=1.0.0; python_version >= "2.7"
@@ -0,0 +1,680 @@
1
+ The git_well Module
2
+ ===================
3
+
4
+
5
+ |Pypi| |PypiDownloads| |GithubActions| |Codecov| |ReadTheDocs|
6
+
7
+ +------------------+----------------------------------------------+
8
+ | Read the docs | https://python-git-well.readthedocs.io |
9
+ +------------------+----------------------------------------------+
10
+ | Github | https://github.com/Erotemic/git_well |
11
+ +------------------+----------------------------------------------+
12
+ | Pypi | https://pypi.org/project/git_well |
13
+ +------------------+----------------------------------------------+
14
+
15
+ Git Well is a collection of git command line tools and is also a Python
16
+ module.
17
+
18
+ Installing this module installs the ``git-well`` command, which is a modal CLI
19
+ into several new git commands. These git commands are also exposed as
20
+ standalone "git" executables.
21
+
22
+ In other words after you:
23
+
24
+ .. code:: bash
25
+
26
+ pip install git-well
27
+
28
+ To get CLI argument completion install `autocomplete
29
+ <https://pypi.org/project/argcomplete/>`_, and you can enable global
30
+ auto-completion
31
+
32
+ .. code:: bash
33
+
34
+ pip install argcomplete
35
+ mkdir -p ~/.bash_completion.d
36
+ activate-global-python-argcomplete --dest ~/.bash_completion.d
37
+ source ~/.bash_completion.d/python-argcomplete
38
+
39
+ And add this to your .bashrc
40
+
41
+ .. code:: bash
42
+
43
+ if [ -f "$HOME/.bash_completion.d/python-argcomplete" ]; then
44
+ # shellcheck disable=SC1091
45
+ source "$HOME"/.bash_completion.d/python-argcomplete
46
+ fi
47
+
48
+
49
+ NOTE: if you know of a way to make this easier please let me know!
50
+
51
+
52
+ Then you can run
53
+
54
+ .. code:: bash
55
+
56
+ # Show all the commands exposed by this repo.
57
+ git well --help
58
+
59
+ git well sync --help
60
+
61
+ # OR
62
+
63
+ git sync
64
+
65
+
66
+ Top Level CLI:
67
+
68
+ .. code::
69
+
70
+ usage: git-well [-h] {squash_streaks,branch_upgrade,sync,branch_cleanup,track_upstream,rebase_add_continue,remote_protocol,discover_remote} ...
71
+
72
+ options:
73
+ -h, --help show this help message and exit
74
+
75
+ commands:
76
+ {squash_streaks,branch_upgrade,sync,branch_cleanup,track_upstream,rebase_add_continue,remote_protocol,discover_remote}
77
+ specify a command to run
78
+ squash_streaks Squashes consecutive commits that meet a specified criteiron.
79
+ branch_upgrade Upgrade to the latest "dev" branch. I.e. search for the branch
80
+ sync Sync a git repo with a remote server via ssh
81
+ branch_cleanup Cleanup branches that have been merged into main.
82
+ track_upstream Set the branch upstream with sensible defaults if possible.
83
+ rebase_add_continue
84
+ A single step to make rebasing easier.
85
+ remote_protocol Helper to change a remote from https to ssh / git for a specific user /
86
+ discover_remote Attempt to discover a ssh remote based on an ssh host.
87
+
88
+
89
+
90
+
91
+ The tools in this module are derived from:
92
+
93
+ * https://github.com/Erotemic/git-sync
94
+ * https://github.com/Erotemic/local/tree/main/git_tools
95
+
96
+
97
+
98
+ Incomplete submodules during source archiving
99
+ ---------------------------------------------
100
+
101
+ ``git-well archive-source`` preserves each committed submodule gitlink when
102
+ possible. If a submodule is uninitialized, its requested commit is unavailable,
103
+ or its export fails, the command warns and finishes with the remaining source.
104
+ The archive's ``GIT_WELL_ARCHIVE_INFO.txt`` records each omitted submodule and
105
+ the commit that could not be included. A failed clone is removed from staging
106
+ rather than packaged as a partial checkout. Nested submodules are omitted when
107
+ their parent cannot be exported. The superproject commit and its gitlinks stay
108
+ unchanged.
109
+
110
+ To include a different locally available submodule commit instead, opt in to
111
+ ``--submodule-revision checkout``; the manifest identifies any divergence
112
+ from its parent gitlink.
113
+
114
+ Archiving pull-request review state
115
+ -----------------------------------
116
+
117
+ ``git archive-source`` normally archives the committed checkout and the
118
+ history reachable from the current ``HEAD``. When reviewing a pull request
119
+ from a contributor fork, use ``--all-branches`` to also preserve every local
120
+ branch and every remote-tracking branch that has already been fetched into the
121
+ superproject repository:
122
+
123
+ .. code:: bash
124
+
125
+ git remote add contributor git@github.com:contributor/project.git
126
+ git fetch contributor
127
+ git archive-source --all-branches
128
+
129
+ The archive operation itself does not contact ``origin``, ``contributor``, or
130
+ any other configured remote. It copies the locally cached ``refs/heads/*`` and
131
+ ``refs/remotes/*`` state, so the unpacked archive can run commands such as
132
+ ``git branch --all``, ``git log contributor/topic``, and
133
+ ``git diff main...contributor/topic`` even if the original fork is no longer
134
+ reachable. The archived working tree remains detached at the exact original
135
+ ``HEAD`` commit. ``--all-branches`` is opt-in, applies to the superproject,
136
+ honors positive ``--depth`` values from each included branch tip, and cannot
137
+ be combined with source-only ``--depth 0`` archives.
138
+
139
+ Use ``--branches`` when only specific branches are needed. Pass branch names
140
+ separated by spaces, using local names or locally cached remote-tracking names:
141
+
142
+ .. code:: bash
143
+
144
+ git archive-source . --branches main topic/one contributor/pr/123
145
+
146
+ Only the named branch refs are retained. The original checkout ``HEAD`` and its
147
+ history are also preserved, detached, even if its branch was not selected.
148
+ For finite ``--depth`` values, each named branch tip and the checkout ``HEAD``
149
+ gets its own history window. The archive keeps their union, so shared ancestry
150
+ can make the history visible from a tip deeper than the requested minimum.
151
+ Missing or ambiguous branch names are errors; use ``refs/heads/...`` or
152
+ ``refs/remotes/...`` when both namespaces have the same display name. No remote
153
+ fetch is performed. ``--branches`` cannot be used with ``--all-branches`` or
154
+ ``--depth 0``. An incremental ``--patch`` archive must use the same selected
155
+ branch names as its base archive (branch tips may advance).
156
+
157
+ Large tracked files that are useful upstream but unnecessary in a handoff can
158
+ be omitted from the materialized archive checkout without rewriting Git
159
+ history. ``--exclude-path`` accepts archive-root-relative files, directories,
160
+ or fnmatch-style selectors, including paths inside included submodules:
161
+
162
+ .. code:: bash
163
+
164
+ git-well archive_source . \
165
+ --exclude-path 'tpl/segment-anything-2/notebooks' \
166
+ 'tpl/Open-GroundingDino/config/instances_val2017.json'
167
+
168
+ For history-bearing repositories, the default ``--history-blobs full`` keeps
169
+ the corresponding blobs reachable in ``.git`` and the staged checkout uses
170
+ sparse-checkout metadata so ``git status`` remains clean. This removes the
171
+ duplicate materialized copy rather than modifying commit IDs or creating an
172
+ invalid object graph.
173
+
174
+ For handoff archives where those paths are deliberately disposable, add
175
+ ``--history-blobs sparse``:
176
+
177
+ .. code:: bash
178
+
179
+ git-well archive_source . \
180
+ --exclude-path 'tpl/segment-anything-2/notebooks' \
181
+ 'tpl/Open-GroundingDino/config/instances_val2017.json' \
182
+ --history-blobs sparse
183
+
184
+ This turns each affected history-bearing checkout into a real partial/promisor
185
+ repository. Reachable blobs associated with excluded paths are omitted from the
186
+ local object database while commit and tree hashes remain unchanged. Git marks
187
+ the remaining packs as promisor packs, so ``git fsck --full`` recognizes the
188
+ missing blobs as intentional. Accessing one of those blobs, or running
189
+ ``git sparse-checkout disable``, may lazily fetch it from the recorded promisor
190
+ remote. The archive manifest records the affected repositories, path count,
191
+ blob count, raw omitted bytes, and promisor URL.
192
+
193
+ ``history-blobs=sparse`` applies selectors across reachable history, not just
194
+ the current checkout, so old versions of an excluded notebook or dataset are
195
+ omitted as well. git-well prefers a configured remote already known locally to
196
+ contain the archived commit; otherwise non-redacted archives use the source
197
+ checkout itself as the truthful fallback promisor. ``--redact-local-paths``
198
+ therefore requires a non-local configured remote known to contain the commit.
199
+ With ``--depth 0``, there is no Git metadata to prune and selected paths are
200
+ simply left out of the source-only tree.
201
+
202
+ Repository-specific archivers can extend the same staging machinery through
203
+ the Python API. Prepare hooks may add generated payloads to the committed
204
+ checkout, while validation hooks run after git-well writes its metadata and
205
+ immediately before serialization:
206
+
207
+ .. code:: python
208
+
209
+ from git_well.archive_source import archive_source
210
+
211
+ def prepare(context):
212
+ report = context.archive_root / 'PROJECT_ARCHIVE_REPORT.txt'
213
+ report.write_text('project-specific report\n')
214
+ context.add_generated_excludes('PROJECT_ARCHIVE_REPORT.txt')
215
+
216
+ def validate(context):
217
+ assert context.manifest_path.exists()
218
+
219
+ archive_source(
220
+ repo_dpath='.',
221
+ depth=100,
222
+ prepare=prepare,
223
+ validate=validate,
224
+ )
225
+
226
+ For workflows that need direct control, ``stage_source_archive()`` exposes the
227
+ same context manager before metadata finalization and archive writing. These
228
+ extension points are programmatic only; the command-line interface does not
229
+ execute arbitrary hooks.
230
+
231
+ Incremental source archives
232
+ ---------------------------
233
+
234
+ History-bearing source archives can also be used as bases for small incremental
235
+ updates. First create a normal archive, then make one or more descendant commits
236
+ and request a patch against the closest compatible archive recorded by git-well:
237
+
238
+ .. code:: bash
239
+
240
+ git-well archive_source . -o project-base.tar.gz
241
+ # make and commit changes
242
+ git-well archive_source . --patch auto -o project-update.tar.gz
243
+
244
+ Patch mode requires the superproject ``.git`` directory. Source-only
245
+ ``--depth 0`` archives are not supported as bases or targets. Patch transport
246
+ supports the descendant-history case: the base and target must use the same
247
+ superproject history depth, ``--all-branches`` policy, and history-blob policy.
248
+ ``patch=auto`` chooses the compatible recorded archive whose HEAD is closest to
249
+ the target HEAD. An explicit compatible archive path may be passed instead of
250
+ ``auto``.
251
+
252
+ Sparse promisor archives are patch-capable. When both base and target use
253
+ ``--history-blobs sparse``, they must also use the same ``--exclude-path``
254
+ policy. The patch compares the target's locally-present reachable objects with
255
+ what is physically available in the base, then transports only the difference
256
+ in a filtered pack while leaving promised excluded blobs absent. This is more
257
+ precise than a revision-only delta: if a previously omitted blob moves to an
258
+ included path without changing its object ID, the patch carries that now-needed
259
+ old blob even though it is reachable from the base commit. Conversely, changing
260
+ an excluded notebook or dataset does not put the new excluded blob into the
261
+ incremental patch.
262
+
263
+ The standalone applier installs target sparse/promisor metadata before advancing
264
+ the checkout and disables lazy fetching during that operation, so applying the
265
+ patch does not require access to the promisor remote. Each sparse repository
266
+ entry also records a SHA-256 digest of its exact reachable promised-missing
267
+ object set. The applier recomputes that set and runs ``git fsck --full`` with
268
+ lazy fetching disabled, preventing a malformed patch from silently rehydrating
269
+ an omitted blob or promising an extra required object.
270
+
271
+ Changing the sparse exclusion policy requires a new base archive. Removing an
272
+ exclusion can require backfilling historical blobs that the base deliberately
273
+ does not contain; adding an exclusion can require deleting objects already
274
+ present in the base. Refusing that policy change keeps incremental patches
275
+ predictable and preserves the requested size semantics. Path movement under an
276
+ unchanged policy is supported: required blobs are backfilled by object identity
277
+ as needed. Sparse Git-bearing submodules may also jump to unrelated commits;
278
+ the patch transports their exact locally-present target object difference rather
279
+ than silently copying the whole staged submodule object store.
280
+
281
+ Repository-specific Python wrappers use the same mechanism. Prepare and
282
+ validation hooks still see a complete target staging tree; git-well computes the
283
+ incremental transport only after validation, so generated payloads are included
284
+ without requiring patch-specific hooks:
285
+
286
+ .. code:: python
287
+
288
+ archive_source(
289
+ repo_dpath='.',
290
+ depth=100,
291
+ patch='auto',
292
+ prepare=prepare,
293
+ validate=validate,
294
+ )
295
+
296
+ Full-blob patches use Git bundles for new repository objects. Sparse-promisor
297
+ patches use filtered Git object packs that intentionally omit promised blobs. A
298
+ residual filesystem overlay transports generated hook payloads and other non-Git
299
+ differences. Patch archives contain ``GIT_WELL_SOURCE_PATCH.json`` with the exact
300
+ base archive SHA-256 and a standalone ``APPLY_SOURCE_PATCH.py``. The standalone
301
+ applier uses only the Python standard library plus the ``git`` executable, so a
302
+ recipient does not need git-well installed. Extract the patch archive and run the
303
+ script beside its manifest:
304
+
305
+ .. code:: bash
306
+
307
+ python APPLY_SOURCE_PATCH.py /path/to/project-base.tar.gz /path/to/output
308
+
309
+ The script verifies the exact base archive, applies superproject and submodule Git
310
+ object deltas plus residual deletions/overlays, verifies the resulting repository
311
+ HEADs, and prints the reconstructed target source root. Sparse patch generation
312
+ also verifies offline that the reconstructed repositories have the same reachable
313
+ promised-missing objects as the staged target. Installed callers use the same
314
+ implementation through ``git_well.archive_source.apply_source_patch``.
315
+
316
+
317
+ Bounded active history with Git epochs
318
+ --------------------------------------
319
+
320
+ ``git epoch`` periodically moves an exact retired Git epoch into a separate
321
+ history-store repository and replaces the active branch with a new root commit
322
+ that represents the same checkout. Ordinary clones then receive only the
323
+ current epoch, while the archived commits keep their original object IDs,
324
+ merge topology, tags, trees, and blobs.
325
+
326
+ Initialize a repository without changing its active refs:
327
+
328
+ .. code:: bash
329
+
330
+ git epoch init --repository ambition \
331
+ --history-store ../ambition-history.git \
332
+ --config-only
333
+
334
+ For a remote history store, also write a committed clone-visible locator before
335
+ planning the first rollover. The history-store ID is stable even if the archive
336
+ URL later moves:
337
+
338
+ .. code:: bash
339
+
340
+ git epoch init --repository ambition \
341
+ --history-store git@github.com:Erotemic/ambition-history.git \
342
+ --history-store-id ambition-history \
343
+ --public-history-url https://github.com/Erotemic/ambition-history.git \
344
+ --public-history-browse-url https://github.com/Erotemic/ambition-history \
345
+ --config-only
346
+ git add .git-epoch.yaml
347
+ git commit -m "Record Git epoch history location"
348
+
349
+ A checkpoint using a remote history store refuses to proceed until this file is
350
+ committed and agrees with the local repository/store identity.
351
+
352
+ For managed submodules, initialize the child repositories as well and classify
353
+ each superproject occurrence before a recursive checkpoint:
354
+
355
+ .. code:: bash
356
+
357
+ git epoch configure-submodule renderer epoch --repository renderer
358
+ git epoch configure-submodule third_party/upstream external
359
+
360
+ Before touching production remotes, the same workflow can be rehearsed against
361
+ disposable local bare remotes. ``sandbox create`` clones the current checked-out
362
+ state, removes non-sandbox remotes from those clones, and records the original
363
+ URLs only as metadata. ``sandbox publish`` rechecks containment immediately
364
+ before rewriting refs:
365
+
366
+ .. code:: bash
367
+
368
+ SANDBOX_DPATH=$(mktemp -d "${TMPDIR:-/tmp}/git-well-epoch-sandbox.XXXXXX")
369
+ git epoch sandbox create --recursive --all-submodules=epoch \
370
+ --output "$SANDBOX_DPATH"
371
+ git epoch sandbox run "$SANDBOX_DPATH" --bundle
372
+
373
+ The staged ``sandbox plan``, ``sandbox apply``, ``sandbox publish``, and
374
+ ``sandbox verify`` commands expose the same phases when the rehearsal should be
375
+ inspected between steps. Verification fresh-clones every repository using only
376
+ sandbox remotes and composes those clones at the translated gitlinks. Git admin
377
+ directories are kept flat and separate from the recursive worktree, avoiding
378
+ platform path growth while still checking the combined parent/submodule tree.
379
+
380
+ Use ``git epoch stats`` to inspect the physical local history store and each
381
+ archived epoch. The report separates shared-store bytes from standalone bundle
382
+ bytes because epochs can share Git objects. In a sandbox, ``sandbox stats`` also
383
+ reports active bare-remote sizes and the recursive fresh-clone size; add
384
+ ``--source-archive`` to build and measure the same full-history ``tar.gz`` shape
385
+ used by ``archive_source``:
386
+
387
+ .. code:: bash
388
+
389
+ git epoch sandbox stats "$SANDBOX_DPATH"
390
+ git epoch sandbox stats "$SANDBOX_DPATH" --source-archive
391
+
392
+ Run ``git epoch gc`` from a managed sandbox worktree when you also want to
393
+ measure repacking savings. It reports before/after file bytes and allocated
394
+ filesystem bytes, then deep-verifies the archive after packing.
395
+
396
+ A checkpoint can be split into an inspectable, resumable preparation and a
397
+ separate publication step. Keep the plan outside the worktree so writing it
398
+ does not make the checkpoint immediately dirty:
399
+
400
+ .. code:: bash
401
+
402
+ CUTOVER_DPATH="$HOME/ambition-epoch-cutover"
403
+ mkdir -p "$CUTOVER_DPATH"
404
+ PLAN="$CUTOVER_DPATH/checkpoint.yaml"
405
+
406
+ git epoch plan --recursive --bundle -o "$PLAN"
407
+ git epoch apply "$PLAN"
408
+ git epoch inspect
409
+ git epoch publish --plan "$PLAN"
410
+
411
+ ``apply``, ``publish``, and deep verification print elapsed-time progress to
412
+ stderr by default while keeping their YAML result on stdout. Pass ``--quiet``
413
+ when scripting without progress output. Archive refs are pushed per repository
414
+ in one atomic batch, and deep verification fetches each repository's archived
415
+ refs in one batch before one ``git fsck``.
416
+
417
+ ``apply`` archives and verifies the retiring epoch before any active branch is
418
+ rewritten. Until ``publish`` succeeds, manifest entries are marked
419
+ ``prepared``. Use ``git epoch abort --plan "$PLAN"`` to discard a prepared
420
+ transaction before any successor branch has been adopted.
421
+
422
+ After publication, verify the archive and reconstruct archaeology checkouts as
423
+ needed:
424
+
425
+ .. code:: bash
426
+
427
+ git epoch verify --deep
428
+ git epoch reconstruct --recursive -o ../ambition-history-view
429
+
430
+ Publication also maintains a human-facing ``main`` branch in the history store
431
+ and mirrors committed archived branches/tags under ``archive/...`` refs. The
432
+ canonical machine authorities remain ``refs/meta/main`` and ``refs/epochs/...``.
433
+ For a history store created by an older git-epoch version, backfill those
434
+ browsing views idempotently with:
435
+
436
+ .. code:: bash
437
+
438
+ git epoch history-sync
439
+
440
+ A normal clone of the history repository can then browse archived branches
441
+ without custom refspecs. ``main`` contains a generated ``README.md`` and
442
+ ``archive-index.yaml`` explaining the store and mapping the canonical refs to
443
+ the browsing refs.
444
+
445
+ Once publication and verification are complete, an existing active checkout may
446
+ still contain unreachable retired objects through its reflog. ``compact``
447
+ validates the published lineage, expires only unreachable reflog entries, runs
448
+ ``git gc --prune=now``, and reports before/after Git-directory sizes:
449
+
450
+ .. code:: bash
451
+
452
+ git epoch compact --recursive
453
+
454
+ Reconstruction fetches the exact archived commits and creates local
455
+ ``refs/replace`` objects that connect each successor root to its recorded
456
+ predecessor. The archived commit objects themselves are not rewritten.
457
+
458
+ A successor root records immutable lineage and the logical history-store ID,
459
+ not a machine-local archive path. ``.git-epoch.yaml`` supplies the movable public
460
+ locator. A fresh clone can therefore explain its split history immediately:
461
+
462
+ .. code:: bash
463
+
464
+ git epoch status
465
+ git epoch inspect
466
+
467
+ ``status`` does not contact the public archive when local attachment is absent.
468
+ ``inspect`` and ``reconstruct`` may use the committed public locator read-only.
469
+ To create machine-local management state, validate and attach the archive:
470
+
471
+ .. code:: bash
472
+
473
+ git epoch attach
474
+
475
+ Maintainers may override the public fetch URL with a writable/local endpoint
476
+ while keeping the same logical store identity:
477
+
478
+ .. code:: bash
479
+
480
+ git epoch attach --history-store git@github.com:Erotemic/ambition-history.git
481
+
482
+ Attachment verifies the public locator, successor-root trailers, archive
483
+ manifest, successor commit/tree, and predecessor commit/tree before writing
484
+ ``.git/epoch/config.yaml``.
485
+
486
+ Version one intentionally requires SHA-1 repositories and a clean single
487
+ worktree. By default checkpoint planning refuses extra active branches because
488
+ they would keep the retired epoch reachable. Maintainers can explicitly use
489
+ ``--retire-extra-branches`` to archive those branch tips under their original
490
+ names and delete the auxiliary active refs atomically during publication. See
491
+ ``docs/planning/git_epoch.md`` for the data model, safety invariants, recursive
492
+ submodule semantics, and deferred scope.
493
+
494
+
495
+ Tracking large files with IPFS
496
+ ------------------------------
497
+
498
+ ``git-well`` also exposes an experimental ``git ipfs`` helper for keeping
499
+ large payloads out of Git while tracking reproducible IPFS CIDs in small
500
+ ``*.ipfs`` sidecar files. There is intentionally no repository-local IPFS
501
+ store and no required ``git ipfs init`` step: Kubo still owns its normal
502
+ ``$IPFS_PATH`` repository, while Git only tracks small sidecar metadata.
503
+
504
+ The minimum supported Kubo version is **0.37.0**. This is the first Kubo
505
+ release with ``ipfs add --pin-name``, which ``git ipfs add --name`` uses to
506
+ assign a human-readable name at import time.
507
+
508
+ The intended happy path is:
509
+
510
+ .. code:: bash
511
+
512
+ git ipfs doctor
513
+ git ipfs add data/ --name my-data
514
+ git commit -m "Track data with IPFS"
515
+
516
+ When you know the peer that is likely to provide the content, record it during
517
+ add:
518
+
519
+ .. code:: bash
520
+
521
+ git ipfs add data/ --name my-data --suggested-peers 12D3KooW...
522
+
523
+ A collaborator can then materialize the payloads with:
524
+
525
+ .. code:: bash
526
+
527
+ git clone <repo-url>
528
+ cd <repo>
529
+ git ipfs doctor
530
+ git ipfs pull
531
+
532
+ The sidecar stores the CID, relative path, object kind, byte size, and the
533
+ CID-affecting import settings. Volatile local details such as mtimes, command
534
+ elapsed time, and machine-specific cache state are intentionally left out of
535
+ the committed sidecar so repeated runs stay reviewable.
536
+
537
+ Sidecar schema v1
538
+ ~~~~~~~~~~~~~~~~~
539
+
540
+ The ``schema_version: 1`` contract is intentionally small and YAML-first.
541
+ Unknown fields should be ignored by readers, and fields that are not needed to
542
+ materialize content should be treated as advisory. This keeps hand-written
543
+ sidecars easy to review and gives future versions room to add optional metadata
544
+ without breaking old repositories.
545
+
546
+ .. code:: yaml
547
+
548
+ schema_version: 1
549
+ type: ipfs-sidecar
550
+ cid: bafy...
551
+ rel_path: data
552
+ kind: directory
553
+ size_bytes: 123456
554
+ num_files: 42
555
+ pin_name: my-data
556
+ import:
557
+ recursive: true
558
+ cid_version: 1
559
+ raw_leaves: false
560
+ suggested_peers:
561
+ - 12D3KooW...
562
+ - /ip4/203.0.113.10/tcp/4001/p2p/12D3KooW...
563
+
564
+ Required fields for materialization are ``cid`` and ``rel_path``. The
565
+ ``import`` mapping records options that affect CID reproducibility.
566
+ ``pin_name``, sizes, counts, and ``suggested_peers`` are useful metadata, but a
567
+ reader should still be able to pull content without them.
568
+
569
+ Sidecars may include peer hints. Bare peer IDs are useful hints when routing
570
+ can discover addresses; full multiaddrs are more reliable when known.
571
+ ``git ipfs pull`` makes a best-effort attempt to connect to ``suggested_peers``
572
+ before downloading. Peer hints can also be inspected or connected manually:
573
+
574
+ .. code:: bash
575
+
576
+ git ipfs peers
577
+ git ipfs peers --connect
578
+
579
+ To make the data retrievable by others, configure a Kubo remote pinning service
580
+ and push sidecar CIDs:
581
+
582
+ .. code:: bash
583
+
584
+ ipfs pin remote service add <service-name> <endpoint> <key>
585
+ git ipfs push --service <service-name>
586
+
587
+ Useful inspection commands:
588
+
589
+ .. code:: bash
590
+
591
+ git ipfs status
592
+ git ipfs status --full
593
+ git ipfs export --emit_bash
594
+
595
+ Dogfood checklist
596
+ ~~~~~~~~~~~~~~~~~
597
+
598
+ When changing this workflow, test it on a scratch branch with a small real
599
+ payload before publishing the change:
600
+
601
+ .. code:: bash
602
+
603
+ git ipfs doctor
604
+ mkdir -p .git-well-ipfs-smoke
605
+ printf 'hello from git ipfs\n' > .git-well-ipfs-smoke/payload.txt
606
+ git ipfs add .git-well-ipfs-smoke --name git-well-ipfs-smoke
607
+ git status --short .gitignore .git-well-ipfs-smoke.ipfs
608
+ rm -rf .git-well-ipfs-smoke
609
+ git ipfs pull .git-well-ipfs-smoke.ipfs
610
+ git ipfs status .git-well-ipfs-smoke.ipfs
611
+
612
+ The helper script ``dev/ipfs_dogfood_smoke.sh`` runs the same smoke flow and
613
+ accepts an optional peer hint as its second argument.
614
+
615
+ Troubleshooting
616
+ ~~~~~~~~~~~~~~~
617
+
618
+ ``git ipfs doctor`` is the first command to run when retrieval is confusing.
619
+ Common failure modes are reported with actionable hints:
620
+
621
+ * ``ipfs`` is missing from ``PATH``: install Kubo >= 0.37.0.
622
+ * The Kubo repo is missing: run ``ipfs init`` for Kubo itself. This does not
623
+ create anything inside the Git repository.
624
+ * The daemon/API is offline: start ``ipfs daemon`` or check ``IPFS_PATH``.
625
+ * Retrieval cannot find a CID: check that someone is pinning the content, then
626
+ try ``git ipfs peers --connect`` or add more specific ``suggested_peers``.
627
+ * Named pins fail: upgrade to Kubo >= 0.37.0 or omit ``--name``.
628
+
629
+
630
+ Use Cases
631
+ ---------
632
+
633
+ Have you ever run into this error when you run ``git pull``?
634
+
635
+ .. code::
636
+
637
+ There is no tracking information for the current branch.
638
+ Please specify which branch you want to merge with.
639
+ See git-pull(1) for details.
640
+
641
+ git pull <remote> <branch>
642
+
643
+ If you wish to set tracking information for this branch you can do so with:
644
+
645
+ git branch --set-upstream-to=origin/<branch> the_current_branch
646
+
647
+ I find this a huge pain because it can't even be bothered to fill in `<branch>` so you have to munge the command to type:
648
+
649
+ .. code::
650
+
651
+ git branch --set-upstream-to=origin/the_current_branch the_current_branch
652
+
653
+
654
+ I get why they did this, the branch on the remote might have a different name.
655
+ But... it usually doesn't. That's why I implemented ``git-well track-upstream``.
656
+
657
+
658
+ Running this instead will detect if you are in the simple case and just do it
659
+ for you. Otherwise it will enumerate your options and ask you to pick one.
660
+
661
+ I've found this command to prevent so much disruption that instaling git-well
662
+ install ``git track-upstream`` as its own command.
663
+
664
+
665
+
666
+
667
+ .. |Pypi| image:: https://img.shields.io/pypi/v/git_well.svg
668
+ :target: https://pypi.python.org/pypi/git_well
669
+
670
+ .. |PypiDownloads| image:: https://img.shields.io/pypi/dm/git_well.svg
671
+ :target: https://pypistats.org/packages/git_well
672
+
673
+ .. |GithubActions| image:: https://github.com/Erotemic/git_well/actions/workflows/tests.yml/badge.svg?branch=main
674
+ :target: https://github.com/Erotemic/git_well/actions?query=branch%3Amain
675
+
676
+ .. |Codecov| image:: https://codecov.io/github/Erotemic/git_well/badge.svg?branch=main&service=github
677
+ :target: https://codecov.io/github/Erotemic/git_well?branch=main
678
+
679
+ .. |ReadTheDocs| image:: https://readthedocs.org/projects/python-git_well/badge/?version=latest
680
+ :target: http://python-git-well.readthedocs.io/en/latest/