Add a documented local/offline build profile for Gitoxide CLI QoL

[volt317]

Summary 💡

Gitoxide already exposes several useful build profiles, including lean, lean-async, and small. The small profile appears close to a local-operation build, but discovering the correct combination currently requires manually inspecting the feature graph and checking for transport-related crates such as curl, reqwest, HTTP/TLS backends, and network client features.

This is a QoL/documentation request rather than a request to remove networking support.

Would the project be open to adding a clearly named feature preset such as local, local-only, or offline-local that documents the intended way to build Gitoxide for local repository operations only?

For example:

cargo build --no-default-features --features local

Expected behavior:

• preserve local repository operations: object database, refs, index, worktree, pack/revision traversal where applicable
• omit remote operations requiring network transports
• avoid enabling curl, reqwest, HTTP/TLS, git://, SSH, credential-helper, clone/fetch/push client stacks
• provide an easy target for users packaging Gitoxide in constrained, embedded, audited, CI, or minimal-toolchain environments

This would reduce feature-graph reverse engineering for users who want a smaller local tool build, and would make the existing small/local-operation intent easier to discover and validate.

Motivation 🔦

Gitoxide already provides a highly modular feature architecture, but identifying the smallest practical feature set for local repository operations currently requires manual inspection of the feature graph and transitive dependencies.

A documented local/offline build profile would improve:

1. Build Simplicity
2. Packaging and Distribution
3. Depedency Auditing
4. CI and Build Performance
5. Discoverability
6. Scope Clarification

Technically, this is already supported...but requires enumeration of the process up to the user.

EDIT: To clarify, this is especially useful for MSRV-constrained or frozen-toolchain environments, where reducing the feature graph also reduces the chance of unrelated transport/client dependencies forcing newer transitive crates.

[volt317]

Just checking in to see if this aligns with the project's intended direction or not. If the answer is 'no,' that's perfectly fine. I mainly wanted to understand whether small was the intended CLI profile for such a build rather than a dependency boundary and if the enhancement could make that process easier.

[Byron]

Thanks for bringing this up.

Small was always intended to skip on all the overhead for transport, so I think it will always stay local. From that point of view it makes sense that it's documented as such, making the idea more explicit than it was before. PR are welcome.

[EliahKagan]

In that point of view it makes sense that it's documented as such, making the idea more explicit than it was before

That small does not have cloning at all has been documented since #2186, though I acknowledge there could be areas that haven't been updated or relevant changes (elsewhere than Cargo.toml) since. That fixed the narrow documentation bug described in #2185.

But as discussed in #2185, there may be more than a documentation change that is called for. In #2185 (comment) I mentioned parenthetically:

I also wonder if it would make sense for us to include the clone subcommand in small, just still without any support for network transport.

In #2185 (comment) you (Sebastian Thiel (@Byron)) replied:

This is probably a less surprising alternative to the status quo, and would make small more useful probably without increasing its size too much.

So if the situation is still much the same as it was then, then I think this may require not only more changes than just documentation, but also more changes than just a newly named feature, depending on whether any code reorganization is needed in gix-transport to get local path and file:// transport but nothing else. There might be some currently existing way to build gix-transport with a selection of features that builds support for local transport but not SSH transport--but I do not know of any such way.

[volt317]

Pull request can be found here.

Short summary:

The aim was for network-free builds (--features local) to compile none of the protocol/transport stack. But gix-protocol is a non-optional dependency of gix, and it pulls gix-transport → gix-packetline non-optionally in turn — so every profile compiles all three even when nothing can reach the network. Making gix-protocol optional stalled on one blocker: Tags and Shallow, two plain configuration enums with no transport dependency, were defined inside gix-protocol yet are part of gix's always-compiled remote-config API. Tags is a field of the core Remote struct (fetch_tags, with_fetch_tags), so gix-protocol couldn't be dropped without dragging those types along.

Solution:

Shallow moves to gix-shallow (its domain crate) and Tags to gix-refspec (its only behaviour, to_refspec, is a refspec operation). Both are network-free leaf crates gix already depends on non-optionally, so the types stay available in local. Because of that, gix::remote::fetch::Tags and gix_protocol::fetch::Tags become the same type. With nothing left tethering it to the always-compiled surface, gix-protocol becomes genuinely optional, and local drops gix-protocol, gix-transport, and gix-packetline entirely.

[volt317]

So if the situation is still much the same as it was then, then I think this may require not only more changes than just documentation, but also more changes than just a newly named feature, depending on whether any code reorganization is needed in gix-transport to get local path and file:// transport but nothing else. There might be some currently existing way to build gix-transport with a selection of features that builds support for local transport but not SSH transport--but I do not know of any such way.

That wasn't exactly my use-case, but it is interesting to think about. IIRC gix works on local file operations in repos by default. Are you thinking like a ftp situation? Most people I know just lump that into ssh.

[hiSandog]

A local/offline build profile would be easier to maintain if the docs show both the feature flags and the expected tradeoffs. For example: which network-facing features are removed, whether the resulting binary can still operate on local repos without optional object databases, and what binary size/startup changes users should expect. A CI job that builds the documented profile would keep the recipe from drifting.

[Byron]

Shallow moves to gix-shallow (its domain crate) and Tags to gix-refspec (its only behaviour, to_refspec, is a refspec operation). Both are network-free leaf crates gix already depends on non-optionally, so the types stay available in local. Because of that, gix::remote::fetch::Tags and gix_protocol::fetch::Tags become the same type. With nothing left tethering it to the always-compiled surface, gix-protocol becomes genuinely optional, and local drops gix-protocol, gix-transport, and gix-packetline entirely.

That's sounds great, and it fits into the small moniker while also being cleaner. I will take a look, disposition: merge.

A local/offline build profile would be easier to maintain if the docs show both the feature flags and the expected tradeoffs. For example: which network-facing features are removed, whether the resulting binary can still operate on local repos without optional object databases, and what binary size/startup changes users should expect. A CI job that builds the documented profile would keep the recipe from drifting.

While I welcome more docs, and like the PR that came out of it as it improves gix, I think it's time to close this issue. Let's not forget that gix is a dev tool, and small is just me saying that we should be able to have quite modular builds.

A possible future tool for developers that actually should be stable one day will hopefully be built at some point in the future, and when that happens, it's definitely worth thinking more closely about different kinds of builds and if they are worth it. But not for gix.
Thanks for your understanding.

PS: It looks like the small build is considerably smaller.