~ivilata/gwit-docs

gwit - Web sites over Git (documentation)
More retouches to simple example of working with existing Git repo.
Minor retouches to simple example of working with existing Git repo.
Add warning about general maturity of the project.

refs

master
browse  log 

clone

read-only
https://git.sr.ht/~ivilata/gwit-docs
read/write
git@git.sr.ht:~ivilata/gwit-docs

You can also use your local clone with git send-email.

#gwit - Web sites over Git

gwit is a minimalist system for a Web of replicated, host-neutral, lightweight sites backed by Git.

Drawing inspiration from an article by Solderpunk (creator of the Gemini protocol), gwit tries to be way more simple, lightweight and future-proof than other "decentralized Web" efforts. For that, it relies on the mature and ubiquitous Git distributed VCS and its support of PGP signatures; minimal additions turn plain Git repositories into a Web of hyperlinked sites.

Features and usage:

  • Fit for lightweight sites: personal blogs, books and documentation, reference works (like Wikipedia), and other text-centric, static but frequently updated sites.
  • Turn any Git repo into a site: link to its content regardless of where the repo is hosted.
  • Obstacle-less site creation: no need to pay for a domain, certificate or server, just create a new PGP key for the site repo.
  • Opportunistic hosting: make any gwit site available online by hosting its repo on Git forges or dumb HTTP servers (one or many, all at once).
  • Content replication and availability: readers clone the whole site (with history), clones can be re-published and used safely by others, forever.
  • Enhance existing Web or Gemini sites: make the static site also available from arbitrary locations via gwit, and accessible in the future. Plays well with static site generators.
  • Offline- and privacy-friendly: cloned sites are browsed locally, no network needed.
  • Poor connectivity scenarios: sites can be cloned or updated from offline media (sneakernet, Kiwix).
  • Collaborative content creation: enabled by Git itself (with one per-site curator).

To publish a Git repo as a gwit site, just create a dedicated branch and PGP key to identify the site in gwit URIs, sign the branch's commits with that key, and publish the repo in any number of public locations. No specific software is needed. To make an existing Web/Gemini static site gwit-compatible, add a simple INI file to its repo.

Visiting a site with a gwit client program creates a full-history clone that may be shared online or offline, and preserved for long-time access: it's like a replicated "wayback machine", without archive trust issues or ad hoc crawling. The client may provide local, private browsing, search and content update notifications regardless of poor connectivity or censorship.

gwit supports petnames for friendly site names, and site introductions for small-world network discovery.

Warning: gwit is currently just a specification, with no working clients to retrieve content. You may already create gwit sites though, but keep in mind that the specs may still change.

#Example

Imagine that you already have a Git repo with some text files in its main branch, like source files or a static Web/Gemini site. To make them available via gwit:

  1. Create a dedicated PGP key pair for the site. The gwit site ID looks like 0xfedcba98765432100123456789abcdef76543210 (after the public key's fingerprint).
  2. From main, create the gwit site branch gwit-0x76543210 (after the key's short ID) and save the site public key as /.gwit/self.key there.
  3. Commit to the site branch with a signature from the site key, push to some public location(s) (Git remotes).
  4. Circulate the gwit site ID and at least one Git location.

The repo file /docs/hello.txt thus becomes available via gwit as gwit://0xfedcba98765432100123456789abcdef76543210/docs/hello.txt. If you committed a new file /docs/gwit.txt to the main branch, to publish it via gwit:

  1. Merge main into the site branch gwit-0x76543210.
  2. Commit to the site branch with a signature from the site key, push to public locations.

VoilĂ , the new file is now available as gwit://0xfedcba98765432100123456789abcdef76543210/docs/hello.txt.

Please note that the set of Git remote locations for the site may change in the future, but gwit URIs remain stable nonetheless.

Normative stuff:

Documentation:

Talks:

Client software:

  • gwet (development not yet started)

#Design goals

The design of gwit tries to fulfil the goals in each list below, as much as they don't clash with the goals listed before them.

Functional goals:

  • Clear target: lightweight, static sites (mostly text) with internal and external hyperlinks, and arbitrary Git repositories.
  • Content authentication: it should be possible to verify content authorship and integrity.
  • Hosting independence: sites should not be bound to a specific host or location.
  • Content replication: sites should be easy to copy in their entirety.
  • Privacy: browsing should leak as little information as possible to external parties.
  • Content sharing: copies of sites should be easy to share in their entirety.
  • Offline-first: some browsing (esp. in-site) should be possible regardless of connectivity.
  • Content independence: any content type should be supported (although certain ones may be preferred that match the other goals).
  • File compatibility: content should be accessible as plain files.
  • Content history: past versions of sites should be available; exact versions should be addressable.
  • Forgiveness: site authors should be able to remove or change content permanently if they change their minds.
  • Transport independence: retrieving site content should not be tied to a specific network protocol.
  • Compatibility: it should be easy to publish an existing static site (esp. Web and Gemini) as a gwit site.
  • Small-scale discoverability: finding other sites should be possible without resorting to external services.

Architectural goals:

  • Simplicity and human scale: simple enough to be fully understood and implemented by a single person in reasonable time.
  • Humanism above techno-solutionism: issues with a complex technical solution should be left to human interaction.
  • Long-term readiness: minimally usable after decades, or when platforms no longer support specific tools.
  • Graceful degradation: minimally usable in the face of failing components (like connectivity or software); e.g. via files.
  • Architectural minimalism: avoid complex or unnecessary dependencies.
  • Frugality in resource usage: esp. power consumption (because of complex computations, large memory footprint, or intensive network traffic).
  • Feature minimalism: only provide the features needed to cover functional goals.
  • Ease of adoption: prefer common, existing knowledge over new or complex concepts.
  • Friendliness and transparency: no compulsory abstractions that hide complexity.
  • Feature stability: focus on intended usage and avoid constant extensions to functionality.

The following non-goals are not supported or favoured by the design itself:

  • Heavy content
  • Interactive or dynamic content
  • Tracking and analytics
  • Monetization or economic incentives
  • Modularity (replaceable parts)
  • Extensibility
  • Push semantics
  • Concurrent authoring (multiple keys)