Beagle: git, URIs and all the dirty words

Beagle reimagines git by mapping its operations onto HTTP verbs and URI query parameters, offering a cleaner way to address files, revisions, and branches. The project builds on the simplicity of git's content‑addressed model while introducing a universal addressing layer.

The URI layout follows a familiar pattern: scheme followed by authority, then a path, and finally a query string that can hold versioning information. The scheme identifies the access protocol, the authority denotes the host or repository identifier, the path points to a location within the repository, and the query carries branch, revision, or file offset data. The HTTP specification defines these components (https://www.rfc-editor.org/rfc/rfc7231).

Beagle uses the HTTP verbs exclusively, treating each verb as an orthogonal operation that maps directly onto a git concept. POST retrieves or creates commits, HEAD performs a dry‑run fetch and report, PUT modifies the reflog to set or delete references, and PATCH applies a different version's changes to the worktree.

The command line syntax uses a patch verb followed by a bang modifier to indicate whether an entire branch or a single commit is targeted. For example, applying a single commit to a feature branch can be expressed as be patch ?feature be post #! # merge a branch becomes be patch ?feature! be post '#merge the feature'. Squashing a branch is shown by be patch ?feature! be post '#add a new feature!'. Cherry‑picking a specific commit uses be patch #391a0d33 be post #! The reference implementation lives at https://github.com/beagle-git/beagle and Git's content‑addressed model is described in the official documentation (https://git-scm.com/book/en/v2/Git-Internals-Git-Objects).

GitHub URIs follow a web‑app structure that mixes project, user, and file segments in the path, making them less suitable for direct versioned access. Beagle URIs orthogonalize all the versioning information into the query part to avoid overusing the path for everything (project, user, branch, path). For instance, the path https://github.com/gritzko/beagle/blob/main/keeper/README.md translates to be://replicated.live/keeper/README.md?/beagle GitHub example.

By exposing a universal addressing scheme, Beagle reduces the mental overhead required when switching contexts, especially when using large language models that need precise references. Developers can construct stable links to specific revisions, directories, or file offsets without resorting to cumbersome command memorization. This approach aligns with the broader trend of integrating version control with web‑centric APIs.

Critics note that extending git with a URI scheme may introduce additional layers of indirection and could confuse newcomers who are accustomed to the traditional command set. They also worry that the added syntax might fragment tooling support and require extra education to master.

The project demonstrates that a modest rethinking of how resources are referenced can preserve the elegance of the original model while adding practical flexibility. It shows that simplicity and expressiveness are not mutually exclusive, and that thoughtful design can emerge from reexamining familiar tools.