gitsocial

module

v0.23.0 Latest Latest Go to latest Published: Sep 6, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/gitsocial-org/gitsocial

Links

Open Source Insights

README ¶

GitSocial

Git-native collaboration platform

About · Installation · Quick Start · Documentation · Contributing

About

GitSocial is a CLI/TUI Go binary that stores issues, PRs, and other collaboration in git itself, as commits with structured trailers on gitmsg/* branches.

A single idempotent command mirrors a project from GitHub or other hosts to an S3-compatible bucket you own; the bucket serves a complete static site of the project (code, timeline, issues, releases, etc.), and doubles as a plain git clone source:

gitsocial mirror https://github.com/owner/repo s3://<endpoint>/<bucket>/<prefix>

GitSocial.org is served this way. The forge becomes optional: issues, PRs, releases, and posts can be created with the CLI/TUI (demo) and pushed like any other commits, and other repositories followed through a timeline.

Installation

macOS / Linux with Homebrew

brew trust gitsocial-org/tap
brew install gitsocial-org/tap/gitsocial

Or using installation script

curl -fsSL https://gitsocial.org/install.sh | sh

Windows

scoop bucket add gitsocial https://github.com/gitsocial-org/scoop-bucket.git
scoop install gitsocial

Go

go install github.com/gitsocial-org/gitsocial/cli/gitsocial@latest

Or download a binary from releases.

Quick Start

Mirror a project

gitsocial mirror https://github.com/owner/repo s3://<endpoint>/<bucket>/<prefix> --url https://your-domain/

--url is the site's public address. mirror asks for the bucket credentials on first run; public access and the domain are one-time provider-dashboard steps. On a large repository try -n 100 first (all flags).

Explore a repository in the terminal

Clone it from GitHub or any host, then from the project directory:

gitsocial import     # import issues, PRs, etc
gitsocial tui        # explore in the terminal

Host your own repository on a bucket

gitsocial config credentials set s3.example.com    # paste the access + secret key
gitsocial remote add s3://s3.example.com/mybucket/myrepo --default --site
gitsocial push

Anyone can then fetch it with gitsocial clone s3://s3.example.com/mybucket/myrepo, or with plain git clone from the bucket's public URL.

Documentation

Concepts

Document	Description
GitMsg Protocol	Core message format, headers, refs, versioning
S3 Remote	Buckets as git remotes, canonical URLs
Static Site	Repo website served from the bucket: timeline, issues, PRs, releases, code
Identity Verification	Decentralized trust model, attestation sources, caching
Notifications	Notification types, scopes, and triggers

Extensions

Document	Description	Spec
Social	Posts, comments, lists, timeline, followers	GitSocial
PM	Issues, milestones, sprints, labels, boards	GitPM
Review	Pull requests, feedback, forks, version tracking, cross-forge scenarios	GitReview
Release	Releases, artifacts, checksums, signatures, SBOM	GitRelease
Memo	Tiered memos for knowledge as commits	—

Clients

Document	Description
Agent Skill	AI-assisted workflows for Claude Code, Cursor, and other agents
TUI	Per-view layout diagrams (see also keybindings)
CLI	Commands, flags, output formats
JSON-RPC	Client integration over stdio

Contributing

Platform issues and PRs are disabled on all mirrors. GitSocial uses its own tools for collaboration.

Getting Started

Install GitSocial (see Installation)
Fork the repository on any host (GitHub, GitLab, Codeberg, or self-hosted)
Clone your fork: git clone https://your-host.com/you/gitsocial
Read Architecture for system design, packages, and cache layout

Submitting Pull Requests

git checkout -b feature/my-change         # make changes, commit

gitsocial review pr create \
  --base main \
  --head feature/my-change \
  "Short description of change"

git push origin feature/my-change         # push your branch
gitsocial push                            # push PR metadata

After your first push, request fork registration in the Matrix room so maintainers can discover your PRs and issues.

See Review for the full cross-forge PR workflow.

Reporting Bugs & Requesting Features

gitsocial pm issue create "Bug: description"
gitsocial push

For quick questions or discussion, use the Matrix room.

License

MIT

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cli
gitsocial command clone.go - gitsocial clone: git clone with zero-setup s3:// remote support	clone.go - gitsocial clone: git clone with zero-setup s3:// remote support
library module
clientfetch clientfetch.go - Shared fetch wiring (extension processor lists + fork backfill) for the thin clients (CLI, TUI, RPC).	clientfetch.go - Shared fetch wiring (extension processor lists + fork backfill) for the thin clients (CLI, TUI, RPC).
clientpush clientpush.go - Shared publish orchestration (data push + browser site) for the thin clients (CLI, TUI, RPC).	clientpush.go - Shared publish orchestration (data push + browser site) for the thin clients (CLI, TUI, RPC).
core/cache acceptances.go - Acceptance state: a cross-repo proposal was accepted, keyed on the proposing edit.	acceptances.go - Acceptance state: a cross-repo proposal was accepted, keyed on the proposing edit.
core/fetch backfill.go - Replay extension processors over cached commits whose items row is missing.	backfill.go - Replay extension processors over cached commits whose items row is missing.
core/git bare.go - Bare-repo lifecycle helpers (init, existence check) and a global git config reader.	bare.go - Bare-repo lifecycle helpers (init, existence check) and a global git config reader.
core/gitmsg branch_sync.go - Push/fetch gitmsg/* branches with auto-merge on divergence.	branch_sync.go - Push/fetch gitmsg/* branches with auto-merge on divergence.
core/gitmsg/divergence Package divergence provides a notification source for diverged gitmsg/<ext> branches.	Package divergence provides a notification source for diverged gitmsg/<ext> branches.
core/identity background.go - Background resolution of verified bindings during fetch	background.go - Background resolution of verified bindings during fetch
core/identity/forge forge.go - Forge adapter interface for identity verification	forge.go - Forge adapter interface for identity verification
core/log log.go - Structured logging with configurable levels and output modes	log.go - Structured logging with configurable levels and output modes
core/notifications mentions.go - Mention extraction from commit messages and CommitProcessor	mentions.go - Mention extraction from commit messages and CommitProcessor
core/objstore artifacts.go - release artifact objects under the reserved artifacts/ root.	artifacts.go - release artifact objects under the reserved artifacts/ root.
core/objstore/locals3 command main.go - locals3, a disk-backed local S3 server for development and the site-test fixture builder.	main.go - locals3, a disk-backed local S3 server for development and the site-test fixture builder.
core/protocol hash.go - Hash generation for message content and refs	hash.go - Hash generation for message content and refs
core/result result.go - Generic Result[T] pattern for extension APIs	result.go - Generic Result[T] pattern for extension APIs
core/search format.go - Text formatting for search results	format.go - Text formatting for search results
core/settings backend.go - Backend interface + Manager facade for scope-routed reads/writes.	backend.go - Backend interface + Manager facade for scope-routed reads/writes.
core/storage forks.go - Isolated bare repos for cross-repository diffs	forks.go - Isolated bare repos for cross-repository diffs
core/text split.go - String splitting helpers shared across packages	split.go - String splitting helpers shared across packages
extensions/memo comment.go - Memo comment integration with social extension	comment.go - Memo comment integration with social extension
extensions/pm board.go - Board configuration and kanban view logic	board.go - Board configuration and kanban view logic
extensions/release artifacts.go - Artifact storage on git refs	artifacts.go - Artifact storage on git refs
extensions/review comment.go - PR comment integration with social extension	comment.go - PR comment integration with social extension
extensions/social fetch.go - Social extension fetch wrappers over core/fetch	fetch.go - Social extension fetch wrappers over core/fetch
import email_map.go - Parsing username=email mapping files for import overrides	email_map.go - Parsing username=email mapping files for import overrides
import/github adapter.go - GitHub source adapter using gh CLI	adapter.go - GitHub source adapter using gh CLI
import/gitlab adapter.go - GitLab source adapter using REST API v4	adapter.go - GitLab source adapter using REST API v4
internal/testutil testutil.go - Shared test fixtures: temp cache lifecycle and clonable git repos.	testutil.go - Shared test fixtures: temp cache lifecycle and clonable git repos.
proposals accept.go - Accept a proposal: apply it as the owner's same-repo mirror edit.	accept.go - Accept a proposal: apply it as the owner's same-repo mirror edit.
rpc handler.go - Method registry and dispatch for JSON-RPC server	handler.go - Method registry and dispatch for JSON-RPC server
tui app.go - Main TUI application model, initialization, and event loop	app.go - Main TUI application model, initialization, and event loop
tui/test assert.go - Render assertion helpers for TUI tests	assert.go - Render assertion helpers for TUI tests
tui/tuicore bus.go - Message bus for decoupled extension message handling	bus.go - Message bus for decoupled extension message handling
tui/tuicore/diff intraline.go - Word/char-level highlighting within paired removed/added lines.	intraline.go - Word/char-level highlighting within paired removed/added lines.
tui/tuikeydoc components.go - Component bindings and domain ordering	components.go - Component bindings and domain ordering
tui/tuimemo form_memo.go - Memo create/edit form (subject, body, labels, tier)	form_memo.go - Memo create/edit form (subject, body, labels, tier)
tui/tuipm form.go - Issue creation form using Huh	form.go - Issue creation form using Huh
tui/tuiproposal tuiproposal.go - Adapter from the proposals engine to tuicore's history view.	tuiproposal.go - Adapter from the proposals engine to tuicore's history view.
tui/tuirelease form_release.go - Release creation form using Huh	form_release.go - Release creation form using Huh
tui/tuireview feedback_layer.go - Composable PR-feedback decoration for diff.DisplayPlan.	feedback_layer.go - Composable PR-feedback decoration for diff.DisplayPlan.
tui/tuisocial form_post.go - Social post create/comment/quote/edit form (body + labels)	form_post.go - Social post create/comment/quote/edit form (body + labels)
scripts
testfmt command main.go - streams `go test -json` events as per-test progress (stdlib only)	main.go - streams `go test -json` events as per-test progress (stdlib only)