acquaint.sync#

Private-repository sync for the data root: create the repository private, refuse anything else, guard every push.

init creates the GitHub repository through gh as private, refuses to continue unless gh repo view --json visibility reports PRIVATE, makes the data root its checkout, and installs a pre-push hook. The hook, and push and pull in Python, re-check that:

  • the push goes through origin, which has exactly one URL, the one recorded at init;

  • no pushurl differs from it, and no url.*.pushInsteadOf rewrites it;

  • that URL is one of the forms that name the recorded repository on github.com (github_urls(), the same list the hook spells out);

  • gh reports the repository, on github.com whatever GH_HOST says, as private.

The hook is installed in the repository’s shared hooks folder, executable, and core.hooksPath points at it by absolute path, so linked worktrees are guarded too and a global core.hooksPath cannot silently disable it. init takes over only an empty folder, or a clone of that same repository; it refuses any other existing repository.

What this does not protect, stated plainly:

  • a private repository is access control, not encryption: the host can read it all;

  • git push --no-verify skips the hook;

  • whoever can change this repository’s git config, or which gh runs on PATH, controls what the guard sees;

  • moving the data root breaks the absolute hook path until sync init --existing-only runs again (sync push refuses in that state; a raw git push does not);

  • file names and commit messages carry people’s names;

  • deleting a folder does not remove it from history, other clones, or backups.

git-remote-gcrypt, which would encrypt contents, names and history, is not supported yet: the guard does not recognise its internal push, so init refuses gcrypt:: URLs.

Every git and gh call goes through run, so tests can script gh while git runs for real.

Module Attributes

ACQUAINT

acquaint's own store.

Functions

github_urls(repo)

Every remote URL accepted for a GitHub repository.

init(root, repo, *[, remote_url, create, ...])

Make root a checkout of the private GitHub repository repo, creating it (private) if needed.

pull(root, *[, dry_run, namespace, run])

Re-check the remote and its visibility, then rebase local work onto it (uncommitted edits are stashed and restored).

push(root, *[, message, entities, ...])

Commit, rebase onto the remote, and push, after re-checking the remote, the guard and the visibility.

run_command(args, *[, cwd])

Run git or gh (gh pinned to github.com), capturing text output.

sole_access(repo, *[, run])

Whether only the repository's owner can read it, and why not: private, owned by a person (not an organisation), that person its only collaborator, no invitation pending.

status(root, *[, check_visibility, ...])

Whether the store is synced, where to, uncommitted changes, ahead/behind, the guard, and live visibility.

visibility(repo, *[, run])

PRIVATE, PUBLIC or INTERNAL, as gh reports it now for the repository on github.com.

Classes

SyncNamespace([name, command, subject, ...])

Everything that names the application using this mechanism: one value, so another app can reuse it unchanged.

acquaint.sync.ACQUAINT = SyncNamespace(name='acquaint', command='acquaint sync', subject='profile data', store='profile', description='acquaint profile store (private)', gitignore='# generated, never synced\n_index/\n.DS_Store\n')#

acquaint’s own store.

Type:

The default

class acquaint.sync.SyncNamespace(name='acquaint', command='acquaint sync', subject='profile data', store='profile', description='acquaint profile store (private)', gitignore='# generated, never synced\n_index/\n.DS_Store\n')[source]#

Bases: object

Everything that names the application using this mechanism: one value, so another app can reuse it unchanged.

name prefixes the git config keys (<name>.repo, <name>.remote) and the default commit messages; command is what error messages tell the user to run (<command> init, <command> push); subject is what the guard refuses to push to a non-private repository (“profile data”).

hook_text()[source]#

The shipped pre-push guard with this namespace filled in.

Return type:

str

acquaint.sync.github_urls(repo)[source]#

Every remote URL accepted for a GitHub repository. The pre-push hook spells out the same six forms.

>>> github_urls("example/profiles")
['git@github.com:example/profiles.git', 'git@github.com:example/profiles', 'ssh://git@github.com/example/profiles.git', 'ssh://git@github.com/example/profiles', 'https://github.com/example/profiles.git', 'https://github.com/example/profiles']
Return type:

list[str]

acquaint.sync.init(root, repo, *, remote_url=None, create=True, dry_run=False, namespace=SyncNamespace(name='acquaint', command='acquaint sync', subject='profile data', store='profile', description='acquaint profile store (private)', gitignore='# generated, never synced\n_index/\n.DS_Store\n'), run=<function run_command>)[source]#

Make root a checkout of the private GitHub repository repo, creating it (private) if needed.

Return type:

dict[str, Any]

acquaint.sync.pull(root, *, dry_run=False, namespace=SyncNamespace(name='acquaint', command='acquaint sync', subject='profile data', store='profile', description='acquaint profile store (private)', gitignore='# generated, never synced\n_index/\n.DS_Store\n'), run=<function run_command>)[source]#

Re-check the remote and its visibility, then rebase local work onto it (uncommitted edits are stashed and restored).

Return type:

dict[str, Any]

acquaint.sync.push(root, *, message=None, entities=(), everything=False, allow_markers=(), dry_run=False, namespace=SyncNamespace(name='acquaint', command='acquaint sync', subject='profile data', store='profile', description='acquaint profile store (private)', gitignore='# generated, never synced\n_index/\n.DS_Store\n'), run=<function run_command>)[source]#

Commit, rebase onto the remote, and push, after re-checking the remote, the guard and the visibility.

entities are record folders (people/ada-lovelace): only those, plus STORE_FILES when one of them is a deleted record, are committed; everything else stays uncommitted, so one session does not sweep up another’s unfinished records. Without entities every change is committed, but when a message is given it must name each record being committed (its id appears in the text as a word) unless everything is set; a message naming only some of them is refused, listing the rest. A file holding conflict markers is refused, unless its store-relative path is in allow_markers (a record that quotes a conflict block on purpose). With no message the default one lists the records. A renamed record needs both its old and new folder named.

Return type:

dict[str, Any]

acquaint.sync.run_command(args, *, cwd=None)[source]#

Run git or gh (gh pinned to github.com), capturing text output.

Return type:

CompletedProcess

acquaint.sync.sole_access(repo, *, run=<function run_command>)[source]#

Whether only the repository’s owner can read it, and why not: private, owned by a person (not an organisation), that person its only collaborator, no invitation pending.

This decides whether profile edits may be committed and pushed without the operator reviewing the diff first: nobody else will see them.

Return type:

tuple[bool, str]

acquaint.sync.status(root, *, check_visibility=True, namespace=SyncNamespace(name='acquaint', command='acquaint sync', subject='profile data', store='profile', description='acquaint profile store (private)', gitignore='# generated, never synced\n_index/\n.DS_Store\n'), run=<function run_command>)[source]#

Whether the store is synced, where to, uncommitted changes, ahead/behind, the guard, and live visibility.

With check_visibility, auto_commit says whether edits may be committed and pushed without the operator reviewing them first (sole_access()), and auto_commit_reason says why or why not.

Return type:

dict[str, Any]

acquaint.sync.visibility(repo, *, run=<function run_command>)[source]#

PRIVATE, PUBLIC or INTERNAL, as gh reports it now for the repository on github.com.

Return type:

str