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.
- {git_well-0.3.1 → git_well-0.3.3}/PKG-INFO +2 -2
- git_well-0.3.3/README.rst +680 -0
- {git_well-0.3.1 → git_well-0.3.3}/git_well/__init__.py +1 -1
- git_well-0.3.3/git_well/_utils.py +380 -0
- git_well-0.3.3/git_well/archive_source/__init__.py +20 -0
- git_well-0.3.3/git_well/archive_source/_common.py +117 -0
- git_well-0.3.3/git_well/archive_source/_io.py +443 -0
- git_well-0.3.3/git_well/archive_source/_policy.py +501 -0
- git_well-0.3.3/git_well/archive_source/_prune.py +620 -0
- git_well-0.3.3/git_well/archive_source/_repo.py +1007 -0
- git_well-0.3.3/git_well/archive_source/api.py +902 -0
- git_well-0.3.3/git_well/archive_source/patch.py +1249 -0
- git_well-0.3.3/git_well/archive_source/patch_apply.py +737 -0
- git_well-0.3.3/git_well/epoch/__init__.py +99 -0
- git_well-0.3.3/git_well/epoch/core.py +4499 -0
- git_well-0.3.3/git_well/epoch/locator.py +495 -0
- git_well-0.3.3/git_well/epoch/sandbox.py +1063 -0
- git_well-0.3.3/git_well/epoch/stats.py +329 -0
- git_well-0.3.3/git_well/git_archive_source.py +244 -0
- {git_well-0.3.1 → git_well-0.3.3}/git_well/git_autoconf_gpgsign.py +20 -11
- {git_well-0.3.1 → git_well-0.3.3}/git_well/git_branch_cleanup.py +18 -15
- {git_well-0.3.1 → git_well-0.3.3}/git_well/git_branch_upgrade.py +16 -14
- {git_well-0.3.1 → git_well-0.3.3}/git_well/git_discover_remote.py +22 -18
- git_well-0.3.3/git_well/git_epoch.py +774 -0
- git_well-0.3.3/git_well/git_rebase_add_continue.py +203 -0
- {git_well-0.3.1 → git_well-0.3.3}/git_well/git_remote_protocol.py +95 -56
- {git_well-0.3.1 → git_well-0.3.3}/git_well/git_squash.py +20 -14
- {git_well-0.3.1 → git_well-0.3.3}/git_well/git_squash_streaks.py +39 -32
- {git_well-0.3.1 → git_well-0.3.3}/git_well/git_stats.py +5 -3
- git_well-0.3.3/git_well/git_sync.py +349 -0
- {git_well-0.3.1 → git_well-0.3.3}/git_well/git_track_upstream.py +9 -6
- {git_well-0.3.1 → git_well-0.3.3}/git_well/git_url_components.py +14 -7
- git_well-0.3.3/git_well/ipfs.py +1161 -0
- {git_well-0.3.1 → git_well-0.3.3}/git_well/main.py +14 -2
- {git_well-0.3.1 → git_well-0.3.3}/git_well/patchdir/git_patchdir_apply.py +14 -8
- {git_well-0.3.1 → git_well-0.3.3}/git_well/patchdir/git_patchdir_save.py +5 -5
- {git_well-0.3.1 → git_well-0.3.3}/git_well/patchdir/patchdir_modal.py +2 -2
- {git_well-0.3.1 → git_well-0.3.3}/git_well/repo.py +12 -12
- {git_well-0.3.1 → git_well-0.3.3}/git_well.egg-info/PKG-INFO +2 -2
- {git_well-0.3.1 → git_well-0.3.3}/git_well.egg-info/SOURCES.txt +22 -0
- {git_well-0.3.1 → git_well-0.3.3}/git_well.egg-info/entry_points.txt +1 -0
- {git_well-0.3.1 → git_well-0.3.3}/git_well.egg-info/requires.txt +2 -2
- {git_well-0.3.1 → git_well-0.3.3}/pyproject.toml +3 -1
- {git_well-0.3.1 → git_well-0.3.3}/requirements/runtime.txt +1 -1
- git_well-0.3.3/tests/test_archive_source_branches.py +294 -0
- git_well-0.3.3/tests/test_archive_source_checkout_revision.py +132 -0
- git_well-0.3.3/tests/test_archive_source_ref_patches.py +289 -0
- git_well-0.3.3/tests/test_archive_source_windows_cleanup.py +191 -0
- git_well-0.3.3/tests/test_bugfixes.py +284 -0
- git_well-0.3.3/tests/test_cli.py +3419 -0
- git_well-0.3.3/tests/test_git_epoch.py +1940 -0
- git_well-0.3.3/tests/test_git_portability.py +50 -0
- git_well-0.3.3/tests/test_ipfs.py +337 -0
- git_well-0.3.1/README.rst +0 -283
- git_well-0.3.1/git_well/_utils.py +0 -317
- git_well-0.3.1/git_well/git_archive_source.py +0 -774
- git_well-0.3.1/git_well/git_rebase_add_continue.py +0 -248
- git_well-0.3.1/git_well/git_sync.py +0 -345
- git_well-0.3.1/git_well/ipfs.py +0 -1283
- git_well-0.3.1/tests/test_cli.py +0 -164
- git_well-0.3.1/tests/test_ipfs.py +0 -333
- {git_well-0.3.1 → git_well-0.3.3}/MANIFEST.in +0 -0
- {git_well-0.3.1 → git_well-0.3.3}/git_well/__main__.py +0 -0
- {git_well-0.3.1 → git_well-0.3.3}/git_well/demo/__init__.py +0 -0
- {git_well-0.3.1 → git_well-0.3.3}/git_well/patchdir/__init__.py +0 -0
- {git_well-0.3.1 → git_well-0.3.3}/git_well/py.typed +0 -0
- {git_well-0.3.1 → git_well-0.3.3}/git_well.egg-info/dependency_links.txt +0 -0
- {git_well-0.3.1 → git_well-0.3.3}/git_well.egg-info/top_level.txt +0 -0
- {git_well-0.3.1 → git_well-0.3.3}/requirements/docs.txt +0 -0
- {git_well-0.3.1 → git_well-0.3.3}/requirements/optional.txt +0 -0
- {git_well-0.3.1 → git_well-0.3.3}/requirements/tests.txt +0 -0
- {git_well-0.3.1 → git_well-0.3.3}/setup.cfg +0 -0
- {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.
|
|
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:
|
|
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/
|