giterator 0.4.0__tar.gz → 1.0.0__tar.gz

{giterator-0.4.0 → giterator-1.0.0}/AGENTS.md

@@ -5,10 +5,12 @@
 - **Done means green**: a change is only complete when `./happy.sh` exits 0; do not commit until it does.
 - **No unrelated failures**: if `./happy.sh` fails on something unrelated to your changes, do NOT assume it is a pre-existing problem and proceed anyway. Stop immediately and ask the user how to proceed.
 - **Docs for everything public**: new functionality or public API changes must have accompanying docs in `docs/*.rst`
+- **Docs examples must run**: every Python code block and doctest in `docs/*.rst` is executed by pytest via sybil, top to bottom per document in one shared namespace. The root `conftest.py` sandboxes each document (fresh temp cwd, git config isolated), so examples must only touch disk via relative paths or `tmp_path`. Use `.. invisible-code-block: python` for setup that shouldn't render, doctests (`>>>`) to show output or tracebacks, and `run_pytest` from `sybil.testing` to actually execute fixture-style test examples.
 - **No em-dashes or parenthetical asides in prose**: in `docs/*.rst` prose and Python docstrings, never use em-dashes, and never tuck a clause inside parentheses; rephrase with commas or separate sentences. This does not apply to code comments or agent-facing notes such as this file, where both are fine.
 - **No stacked headings in docs**: a heading in `docs/*.rst` must be followed by prose, never immediately by a sub-heading. Add a short lead-in or merge the levels.
 - **Type-annotate public APIs**: all public functions and classes need type annotations; mypy is the gate
 - **Use `compare()` in tests**: assert with `compare(actual, expected=...)`, using `StringComparison` for pattern matches. Bare `assert` only for booleans and `isinstance` (which type-narrows for mypy).
+- **No `pytest.MonkeyPatch`**: use testfixtures instead. `TempDirectory(cwd=True)` replaces `monkeypatch.chdir`; for mocking, prefer `Replacer` methods (`replace.in_environ`, `replace.on_class`, `replace.in_module`), or the `replace_in_environ`/`replace_on_class`/`replace_in_module` context managers for one-offs.
 - **No `noqa`, ever**: this project has zero linter suppressions; don't add them. Fix the underlying issue instead.
 - **No `docs/changes.rst` edits during development**: that file is updated at release time, not as part of feature work.
 
@@ -57,3 +59,10 @@ Testing specifics:
   `COVERAGE_PROCESS_START` and the `coverage-enable-subprocess` dev dependency measures
   them, so coverage runs in parallel mode.
 - Tests exercise real git via temporary repositories, so a `git` binary is required.
+- Docs examples are collected via the root `conftest.py` (sybil); `testpaths` includes
+  `docs`. Sandboxing is done with pytest fixtures requested via `Sybil(fixtures=...)`:
+  a module-scoped fixture spans exactly one document, and the `sandbox` fixture uses
+  that to chdir into a `TempDirectory(cwd=True)` and point
+  `GIT_CONFIG_GLOBAL`/`GIT_CONFIG_SYSTEM` at controlled files, so examples can never
+  read or write the machine's git config or real filesystem paths. The builtin
+  `tmp_path` is also requested, fresh per example.

{giterator-0.4.0 → giterator-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: giterator
-Version: 0.4.0
+Version: 1.0.0
 Summary: Python tools for doing git things.
 Project-URL: Homepage, https://github.com/simplistix/giterator
 Project-URL: Documentation, https://giterator.readthedocs.org/en/latest/
@@ -26,4 +26,17 @@ giterator
 .. |Docs| image:: https://readthedocs.org/projects/giterator/badge/?version=latest
 .. _Docs: http://giterator.readthedocs.org/en/latest/
 
-Python tools for doing git things.
+Python tools for doing git things:
+
+- ``Git`` wraps command-line git for scripting everyday repository operations,
+  with structured access to the log.
+
+- ``read`` and ``write`` replay a repository's history as a series of dated
+  snapshots and turn dated snapshots, such as backups, back into history.
+  The ``giterator`` command line tool packs and unpacks dated files in the
+  same way.
+
+- ``giterator.testing.Repo`` makes sample repositories for automated tests,
+  with machine-independent configuration and single-call commits.
+
+Full documentation is available at http://giterator.readthedocs.org/en/latest/

giterator-1.0.0/README.rst

@@ -0,0 +1,25 @@
+giterator
+=========
+
+|CI|_ |Docs|_
+
+.. |CI| image:: https://github.com/simplistix/giterator/actions/workflows/ci.yml/badge.svg
+.. _CI: https://github.com/simplistix/giterator/actions/workflows/ci.yml
+
+.. |Docs| image:: https://readthedocs.org/projects/giterator/badge/?version=latest
+.. _Docs: http://giterator.readthedocs.org/en/latest/
+
+Python tools for doing git things:
+
+- ``Git`` wraps command-line git for scripting everyday repository operations,
+  with structured access to the log.
+
+- ``read`` and ``write`` replay a repository's history as a series of dated
+  snapshots and turn dated snapshots, such as backups, back into history.
+  The ``giterator`` command line tool packs and unpacks dated files in the
+  same way.
+
+- ``giterator.testing.Repo`` makes sample repositories for automated tests,
+  with machine-independent configuration and single-call commits.
+
+Full documentation is available at http://giterator.readthedocs.org/en/latest/

giterator-1.0.0/conftest.py

@@ -0,0 +1,34 @@
+import os
+from collections.abc import Iterator
+from doctest import ELLIPSIS, REPORT_NDIFF
+
+import pytest
+from sybil import Sybil
+from sybil.parsers.rest import DocTestParser, PythonCodeBlockParser, SkipParser
+from testfixtures import Replacer, TempDirectory
+
+GIT_CONFIG = (
+    b'[user]\n\tname = Giterator\n\temail = giterator@example.com\n[init]\n\tdefaultBranch = main\n'
+)
+
+
+@pytest.fixture(scope='module')
+def sandbox() -> Iterator[None]:
+    # Module scope makes this one sandbox per document: examples create real
+    # repos with relative paths, so each document runs in its own temporary
+    # directory, with git pointed away from the machine's own configuration.
+    with TempDirectory(cwd=True) as tempdir, Replacer() as replace:
+        replace.in_environ('GIT_CONFIG_GLOBAL', tempdir.write('gitconfig', GIT_CONFIG))
+        replace.in_environ('GIT_CONFIG_SYSTEM', os.devnull)
+        yield
+
+
+pytest_collect_file = Sybil(
+    parsers=[
+        DocTestParser(optionflags=REPORT_NDIFF | ELLIPSIS),
+        PythonCodeBlockParser(),
+        SkipParser(),
+    ],
+    pattern='*.rst',
+    fixtures=['sandbox', 'tmp_path'],
+).pytest()

giterator-1.0.0/docs/api.rst

@@ -0,0 +1,28 @@
+API Reference
+=============
+
+Everything documented here is importable directly from ``giterator``, except
+for :class:`~giterator.testing.Repo`, which lives in ``giterator.testing`` so
+that test-only code is never pulled in by normal use.
+
+giterator
+~~~~~~~~~
+
+.. automodule:: giterator
+    :members:
+    :special-members: __call__
+    :member-order: bysource
+
+.. data:: daily
+    :type: Every
+
+    A daily schedule, for use with :func:`read`.
+
+
+giterator.testing
+~~~~~~~~~~~~~~~~~~
+
+.. automodule:: giterator.testing
+    :members:
+    :member-order: bysource
+    :show-inheritance:

giterator-1.0.0/docs/changes.rst

@@ -0,0 +1,77 @@
+.. py:currentmodule:: giterator
+
+Changes
+=======
+
+1.0.0 (6 Jul 2026)
+------------------
+
+.. warning:: Breaking changes:
+
+  - The ``prefix`` parameter of
+    :meth:`Repo.commit_content <giterator.testing.Repo.commit_content>` has been renamed
+    to ``name`` and is now optional.
+
+- Added :func:`read`, which replays the history of a repository as a series of
+  :class:`Giteration` snapshots, either one per commit or taken on a schedule such as
+  :data:`daily`.
+
+- Added :func:`write`, which turns a series of :class:`Giteration` snapshots into commits,
+  useful for turning dated copies of a project, such as backups, into version history.
+  Combining it with :func:`read` allows a repository's history to be resampled.
+
+- The ``giterator`` command line tool has grown ``pack`` and ``unpack`` commands for
+  moving between files with dates in their names and commits in a repository.
+
+- Added :meth:`Git.log`, which returns the commits in a repository as :class:`Commit`
+  instances, giving structured access to the hash, author, committer, dates and full
+  message of each commit.
+
+- :meth:`Repo.commit_content <giterator.testing.Repo.commit_content>` no longer needs a
+  file name, and the content and commit message can now be given when a test cares
+  about them.
+
+- The documentation has been substantially expanded, and every example in it is now
+  executed as part of the test suite.
+
+- Fixed a bug where :meth:`Git.clone` failed when the source repository was given as a
+  relative path.
+
+- Fixed a bug where calling a :class:`Git` instance with environment variable overrides,
+  as :meth:`Git.commit` does when given explicit dates, ran ``git`` with only those
+  variables rather than the full process environment.
+
+0.4.0 (4 Jul 2026)
+------------------
+
+- Moved to a `uv`__-based, ``pyproject.toml``-driven project layout, with ``main`` replacing
+  ``master`` as the default git branch.
+
+  __ https://docs.astral.sh/uv/
+
+- :meth:`Repo.clone <giterator.testing.Repo.clone>` now always ensures a user is configured in
+  the clone, whether specified explicitly, inherited from the source repo, or falling back to
+  the same default as :meth:`Repo.make <giterator.testing.Repo.make>`, so commits made in
+  clones no longer depend on the git config of the machine the tests are running on.
+
+- :meth:`Git.init` can now pin the name of the initial branch, and
+  :meth:`Repo.make <giterator.testing.Repo.make>` does so by default, using ``main``, so branch
+  names in test repos no longer depend on the git config of the machine the tests are running on.
+
+0.3.0 (4 Feb 2026)
+------------------
+
+- General refresh.
+
+- Add ``short`` parameter to methods that return commit hashes,
+  allowing the full commit hash to be returned.
+
+0.2.0 (1 Oct 2021)
+------------------
+
+- Methods that create commits now return the newly-create commit hash.
+
+0.1.0 (28 Sep 2021)
+-------------------
+
+- Initial release

giterator-1.0.0/docs/use.rst

@@ -0,0 +1,341 @@
+.. py:currentmodule:: giterator
+
+Using giterator
+===============
+
+
+Installation
+~~~~~~~~~~~~
+
+giterator is available on the `Python Package Index`__ and can be installed
+with any tools for managing Python environments.
+
+__ https://pypi.org
+
+
+Normal use
+~~~~~~~~~~
+
+:class:`Git` wraps the command-line ``git`` tool, giving common repository
+operations a typed Python method instead of a shell command assembled by
+hand. Point it at an existing work tree, or create one with :meth:`Git.init`:
+
+.. code-block:: python
+
+    from giterator import Git, User
+
+    repo = Git('path/to/repo')
+    repo.init(User('Alice', 'alice@example.com'))
+
+Any git subcommand that doesn't have a dedicated method can still be run
+directly; calling a :class:`Git` instance (or its :meth:`~Git.git` alias)
+runs ``git`` in the work tree and returns its output as a string:
+
+.. code-block:: python
+
+    repo.git('remote', 'add', 'origin', 'git@example.com:some/repo.git')
+
+If the command fails, a :class:`GitError` is raised carrying git's own
+output:
+
+>>> repo.git('merge', 'no-such-branch')
+Traceback (most recent call last):
+...
+giterator.git.GitError: 'git merge no-such-branch' gave return code 1:
+<BLANKLINE>
+merge: no-such-branch - not something we can merge
+...
+
+:meth:`Git.commit` stages everything in the work tree, including new and
+deleted files, and commits it, optionally backdating the author and
+committer:
+
+.. code-block:: python
+
+    from datetime import datetime, timezone
+
+    (repo.path / 'README.rst').write_text('hello')
+    repo.commit('add readme', author_date=datetime(2020, 1, 1, tzinfo=timezone.utc))
+
+:meth:`Git.clone` clones a repo. When the source is a :class:`Git` instance
+with a user configured, that user is carried over to the clone unless a
+different one is given:
+
+.. code-block:: python
+
+    clone = Git.clone(repo, 'path/to/clone')
+
+Branches and tags are created and listed with :meth:`Git.branch`,
+:meth:`Git.branches`, :meth:`Git.tag` and :meth:`Git.tags`, and their commit
+hashes looked up with :meth:`Git.branch_hashes` and :meth:`Git.tag_hashes`:
+
+>>> repo.branch('feature')
+>>> repo.tag('v1.0')
+>>> repo.branches()
+['feature', 'main']
+>>> repo.tags()
+['v1.0']
+
+
+Examining history
+~~~~~~~~~~~~~~~~~~
+
+:meth:`Git.log` returns the commits in a repository as :class:`Commit`
+instances, giving structured access to the hash, author, committer, dates
+and full message of each commit. Here, after committing some docs to go
+with the readme:
+
+.. code-block:: python
+
+    (repo.path / 'docs').mkdir()
+    (repo.path / 'docs' / 'index.rst').write_text('welcome')
+    repo.commit('add docs', author_date=datetime(2020, 2, 1, tzinfo=timezone.utc))
+
+>>> for commit in repo.log():
+...     print(commit.author_date, commit.author.name, commit.message)
+2020-02-01 00:00:00+00:00 Alice add docs
+2020-01-01 00:00:00+00:00 Alice add readme
+
+Any options, revision ranges or paths accepted by ``git log`` can be passed
+as strings, here reversing the order and restricting to commits that touch
+``docs/``:
+
+>>> for commit in repo.log('--reverse', 'docs/'):
+...     print(commit.author_date, commit.message)
+2020-02-01 00:00:00+00:00 add docs
+
+
+Iterating over history
+~~~~~~~~~~~~~~~~~~~~~~
+
+The :func:`read` function replays the history of a repository as a series of
+snapshots taken on a schedule. Each snapshot is a :class:`Giteration` giving
+the path to a checkout of the repository as it was at that point in time,
+along with the revision checked out and the time of the snapshot. The
+examples below read a repository with commits at 10:00 on 1 January, 11:00
+on 2 January and 12:00 on 5 January 2001, all UTC:
+
+.. invisible-code-block: python
+
+    from giterator.testing import Repo
+
+    project = Repo.make('path/to/project')
+    for prefix, day, hour in [('a', 1, 10), ('b', 2, 11), ('c', 5, 12)]:
+        project.commit_content(prefix, datetime(2001, 1, day, hour, tzinfo=timezone.utc))
+
+>>> from giterator import daily, read
+>>> for giteration in read('path/to/project', daily.at(16, 0)):
+...     print(giteration.at, giteration.rev)
+2001-01-01 16:00:00+00:00 5ee580a
+2001-01-02 16:00:00+00:00 e3a9fbb
+2001-01-05 16:00:00+00:00 4f0b0f3
+
+Snapshots are made by cloning the repository into a temporary location, so
+the repository itself is never modified. Each checkout is only valid until
+the next snapshot is requested, and is removed when iteration finishes.
+
+The schedule can be :data:`daily`, anchored to a time of day with
+:meth:`Every.at` as above, or any :class:`~datetime.timedelta` giving the gap
+between snapshots. Without an anchor, the schedule ticks from the date of
+the repository's first commit:
+
+>>> from datetime import timedelta
+>>> for giteration in read('path/to/project', timedelta(days=2)):
+...     print(giteration.at, giteration.rev)
+2001-01-01 10:00:00+00:00 5ee580a
+2001-01-03 10:00:00+00:00 e3a9fbb
+2001-01-07 10:00:00+00:00 4f0b0f3
+
+``start`` begins the schedule somewhere else, with the first snapshot giving
+the repository as it stood at that point:
+
+>>> start = datetime(2001, 1, 4, tzinfo=timezone.utc)
+>>> for giteration in read('path/to/project', daily.at(16, 0), start=start):
+...     print(giteration.at, giteration.rev)
+2001-01-04 16:00:00+00:00 e3a9fbb
+2001-01-05 16:00:00+00:00 4f0b0f3
+
+As the examples above show, points on the schedule where the repository had
+not changed since the previous snapshot are skipped, and iteration stops
+once the most recent commit has been seen. Pass ``skip_unchanged=False`` to
+get exactly one snapshot per point instead, useful when whatever consumes
+them expects evenly spaced samples:
+
+>>> snapshots = read('path/to/project', daily.at(16, 0), skip_unchanged=False)
+>>> for giteration in snapshots:
+...     print(giteration.at, giteration.rev)
+2001-01-01 16:00:00+00:00 5ee580a
+2001-01-02 16:00:00+00:00 e3a9fbb
+2001-01-03 16:00:00+00:00 e3a9fbb
+2001-01-04 16:00:00+00:00 e3a9fbb
+2001-01-05 16:00:00+00:00 4f0b0f3
+
+When no schedule is given, a snapshot is yielded for every commit, with the
+time of each snapshot being the date of its commit:
+
+>>> for giteration in read('path/to/project'):
+...     print(giteration.at, giteration.rev)
+2001-01-01 10:00:00+00:00 5ee580a
+2001-01-02 11:00:00+00:00 e3a9fbb
+2001-01-05 12:00:00+00:00 4f0b0f3
+
+The :func:`write` function does the reverse, turning a series of snapshots
+into commits in a repository, which is useful when you have dated copies of
+a project, such as backups, that you would like to turn into version
+history:
+
+.. invisible-code-block: python
+
+    from pathlib import Path
+
+    for day in '2001-01-01', '2001-02-01':
+        backup = Path('backups') / day
+        backup.mkdir(parents=True)
+        (backup / 'notes.txt').write_text(day)
+
+.. code-block:: python
+
+    from datetime import datetime
+    from giterator import Giteration, write
+
+    write('path/to/new/repo', [
+        Giteration('backups/2001-01-01', datetime(2001, 1, 1)),
+        Giteration('backups/2001-02-01', datetime(2001, 2, 1)),
+    ])
+
+If the target repository does not already exist, it is created. The content
+of each :class:`Giteration` replaces the content of the repository's work
+tree and is committed using its ``at`` date for both the author and
+committer dates, with the ``at`` date as the message when none is given:
+
+>>> [commit.message for commit in Git('path/to/new/repo').log()]
+['2001-02-01T00:00:00', '2001-01-01T00:00:00']
+
+Since :func:`read` yields :class:`Giteration` instances and :func:`write`
+accepts them, the two can be combined to resample a repository's history,
+here as it stood at 4pm each day. Commit messages are preserved, as
+:func:`read` fills in the message of each snapshot's source commit:
+
+>>> from giterator import write
+>>> resampled = write('path/to/resampled', read('path/to/project', daily.at(16, 0)))
+>>> for commit in resampled.log('--reverse'):
+...     print(commit.author_date, commit.message)
+2001-01-01 16:00:00+00:00 a commit
+2001-01-02 16:00:00+00:00 a commit
+2001-01-05 16:00:00+00:00 a commit
+
+The ``giterator`` command line tool builds on the same read/write model to
+move between dated files and commits. ``pack`` looks for files matching a
+:meth:`~datetime.datetime.strftime` pattern, parses the date out of each
+file's name, and commits them oldest first under the name on the right of
+the mapping:
+
+.. code-block:: bash
+
+    giterator pack --repo path/to/repo 'downloads/foo-%Y-%m-%d.csv:foo.csv'
+
+``unpack`` does the reverse, copying files matching the glob pattern on the
+left of the mapping to the path produced by formatting each commit's date
+with the pattern on the right:
+
+.. code-block:: bash
+
+    giterator unpack --repo path/to/repo '*.csv:downloads/foo-%Y-%m-%d.csv'
+
+If any of the paths involved contain a colon, ``--sep`` changes the
+separator used in the mapping.
+
+
+Testing
+~~~~~~~
+
+:class:`~giterator.testing.Repo` is a :class:`Git` subclass built for use in
+automated tests. It configures a user and initial branch name that don't
+depend on the git configuration of the machine running the tests, so the
+same test behaves the same way in every environment, including CI.
+
+The usual pattern is a pytest fixture that makes a fresh repo in a temporary
+directory for each test:
+
+.. code-block:: python
+
+    from pathlib import Path
+
+    import pytest
+    from giterator.testing import Repo
+
+
+    @pytest.fixture()
+    def repo(tmp_path: Path) -> Repo:
+        return Repo.make(tmp_path / 'repo')
+
+
+    def test_something(repo: Repo) -> None:
+        repo.commit_content('data')
+        commit = repo.log()[0]
+        assert commit.message == 'a commit'
+
+.. invisible-code-block: python
+
+    from sybil.testing import run_pytest
+
+    run_pytest(test_something, fixtures=[repo])
+
+    repo = Repo.make(tmp_path / 'sample')
+
+As ``test_something`` shows, :meth:`~giterator.testing.Repo.commit_content`
+makes a commit in a single call: it writes a file, defaulting to
+``sample.txt`` with content derived from its name, and commits with an
+automatically increasing timestamp, so a test can create a string of
+commits without inventing a file name, content, or dates by hand. When a
+test does care about those, or about the commit message, they can all be
+given, and the commit can be placed on a new branch or tagged:
+
+.. code-block:: python
+
+    from datetime import datetime
+
+    repo.commit_content('a')
+    repo.commit_content('b', datetime(2021, 6, 1))
+    repo.commit_content('c', content='some specific content')
+    repo.commit_content('d', message='a specific message')
+    repo.commit_content('e', tag='v1.0')
+    repo.commit_content('f', branch='feature')
+
+That leaves the work tree with one file per call:
+
+>>> sorted(path.name for path in repo.path.iterdir())
+['.git', 'a', 'b', 'c', 'd', 'e', 'f']
+
+:meth:`~giterator.testing.Repo.make` is the usual way to create a
+:class:`~giterator.testing.Repo`.
+A :class:`User` and branch name can be given if the defaults, ``Giterator
+<giterator@example.com>`` and ``main``, don't suit a particular test:
+
+.. code-block:: python
+
+    from giterator import User
+
+    repo = Repo.make(
+        tmp_path / 'repo', user=User('Alice', 'alice@example.com'), branch='trunk'
+    )
+
+:meth:`~giterator.testing.Repo.clone` works like :meth:`Git.clone`, but
+ensures the clone always has a user configured, even when the source has
+none, falling back to the same default as
+:meth:`~giterator.testing.Repo.make`:
+
+.. code-block:: python
+
+    clone = Repo.clone(repo, tmp_path / 'clone')
+
+When a test needs full control over the files in a commit, write them and
+use :meth:`~giterator.testing.Repo.commit`. It works like
+:meth:`Git.commit`, except that when ``commit_date`` is omitted it defaults
+to ``author_date``, so one date is enough to pin both of a commit's
+timestamps:
+
+.. code-block:: python
+
+    (repo.path / 'content.txt').write_text('content')
+    repo.commit('a commit', datetime(2020, 1, 1))

{giterator-0.4.0 → giterator-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "giterator"
-version = "0.4.0"
+version = "1.0.0"
 description = "Python tools for doing git things."
 readme = "README.rst"
 authors = [{ name = "Chris Withers", email = "chris@withers.org" }]
@@ -29,6 +29,7 @@ dev = [
     "pytest>=8",
     "pytest-cov>=6",
     "ruff>=0.9",
+    "sybil>=10.1",
     "testfixtures>=11",
 ]
 docs = [
@@ -45,7 +46,7 @@ packages = ["src/giterator"]
 
 [tool.pytest.ini_options]
 addopts = "-p no:doctest"
-testpaths = ["tests"]
+testpaths = ["tests", "docs"]
 
 [tool.mypy]
 strict = true

giterator-1.0.0/src/giterator/__init__.py

@@ -0,0 +1,15 @@
+from .git import Commit, Git, GitError, User
+from .iterate import Every, Giteration, daily, read, write
+
+
+__all__ = [
+    'Git',
+    'User',
+    'Commit',
+    'GitError',
+    'Every',
+    'daily',
+    'Giteration',
+    'read',
+    'write',
+]

giterator-1.0.0/src/giterator/cli.py

@@ -0,0 +1,88 @@
+from argparse import ArgumentParser, Namespace
+from datetime import datetime
+from glob import glob
+from os import makedirs
+from pathlib import Path
+from re import sub
+from shutil import copy2
+
+from .git import Git
+from .iterate import read
+
+
+def split_mapping(mapping: str, sep: str) -> tuple[str, str]:
+    source, found, target = mapping.partition(sep)
+    if not found:
+        raise SystemExit(f'mapping must contain {sep!r}')
+    return source, target
+
+
+class Command:
+    def add_args(self, parser: ArgumentParser) -> None:
+        parser.add_argument('--repo', type=Path, required=True, help='The repo to work with.')
+        parser.add_argument('--sep', default=':', help='The separator used in the mapping.')
+        parser.add_argument('mapping', help='A source and target, separated by --sep.')
+
+    def __call__(self, args: Namespace) -> None: ...
+
+
+class Pack(Command):
+    """
+    Commit dated files matching a strftime pattern to a repo.
+    """
+
+    def __call__(self, args: Namespace) -> None:
+        pattern, name = split_mapping(args.mapping, args.sep)
+        pattern = str(Path(pattern).expanduser())
+        repo = Git(args.repo.expanduser())
+        if not (repo.path / '.git').exists():
+            repo.init()
+        found = []
+        for source in glob(sub('%[a-zA-Z]', '*', pattern)):
+            try:
+                at = datetime.strptime(source, pattern)
+            except ValueError:
+                continue
+            found.append((at, source))
+        for at, source in sorted(found):
+            copy2(source, repo.path / name)
+            rev = repo.commit(Path(source).name, author_date=at, commit_date=at, allow_empty=True)
+            print(rev, source)
+
+
+class Unpack(Command):
+    """
+    Write files matching a glob pattern to dated copies for each commit in a repo.
+    """
+
+    def __call__(self, args: Namespace) -> None:
+        pattern, target = split_mapping(args.mapping, args.sep)
+        target = str(Path(target).expanduser())
+        for giteration in read(args.repo.expanduser()):
+            assert giteration.at is not None
+            for path in sorted(giteration.path.glob(pattern)):
+                if '.git' in path.parts:
+                    continue
+                dest = Path(giteration.at.strftime(target))
+                makedirs(dest.parent, exist_ok=True)
+                copy2(path, dest)
+                print(dest)
+
+
+def parse_args() -> Namespace:
+    parser = ArgumentParser()
+    subparsers = parser.add_subparsers(dest='command')
+    subparsers.required = True
+    for command_class in Command.__subclasses__():
+        command_parser = subparsers.add_parser(
+            command_class.__name__.lower(), help=command_class.__doc__
+        )
+        command = command_class()
+        command.add_args(command_parser)
+        command_parser.set_defaults(command=command)
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    args.command(args)