git-remote-gemini
fetch and push git repositories over the project gemini protocol
Installation
Save the file git-remote-gemini into a directory in your shell path and mark it executable. It must have the exact name "git-remote-gemini".
Python is the only dependency. git-remote-gemini has been tested with Python 3.13. Only modules that are part of the standard python distribution are used.
Usage
Simply use "gemini://" URLs in git. for example
Server Configuration
Similar to git's http support, there is a "dumb" protocol and a "smart" protocol. The smart protocol is faster, but the dumb protocol requires less support from the server.
To support the dumb protocol, all that needs to be done is to serve the git directory as static files. The dumb protocol supports fetching only, not pushing.
At this time, no servers are known to support the smart protocol out of the box. See the following section on implementation details if you wish to add support.
Protocol Details
This section contains implementation details to help anyone adding support to server software. This section is not important for end users.
Support from the server is only necessary to use the "smart" protocol. Git repositories can be served as static files without any further configuration.
`git-remote-gemini` is run automatically by git when it is asked to handle a gemini:// url. To run it manually make sure the environment is set up properly:
git remote-helpers documentation has more information on how to interact with remote-helpers.
git-remote-gemini supports three commands: connect and fetch. connect is used to invoke the "smart" protocol for either fetching or pushing, list and fetch are used to invoke the "dumb" protocol for fetching only.
The connect Command
Either `connect git-upload-pack` for fetching or `connect git-receive-pack` for pushing.
In response, git-helper-gemini will make a gemini request to the url of the remote repository with a query string of either `?git-upload-pack` or `?git-receive-pack`.
If the server supports the "smart" protocol, it must respond with
Any other mime type is interpreted to mean that the "smart" protocol is not available.
The server then needs to run
and connect both standard in and out of the process to the request socket. Data must be transferred in both directions between the request socket and the git process until it exits.
The list Command
The list command will request the file "info/refs", relative to the base url given.
The fetch Command
The first time the fetch command is used, a request will be made for the file "objects/info/packs", then for each line in that file, a request is made for a file of the form "objects/pack/pack-[name].idx".
Every time the fetch command is run, the following algorithm is run:
1. look for the object in the local git repository
2. if not found, look for the object in the pack file indices. if found, download the corresponding pack file "objects/pack/pack-[name].pack"
3. if still not found, look for a loose object with the name "objects/[HH]/[HASH]" where "[HH]" is the first two characters of the hash and "[HASH]" is the remainder
4. insert object in git database. if the object was still not found, exit
5. repeat recursively for all dependent objects