specs/GITSOCIAL.md · main · 2026-09-26

GitSocial Extension Specification

GitSocial is a social networking extension for the GitMsg protocol.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

1. Messages

1.1. Types

Message types:

post: Standard message
comment: Response to content
repost: Share without commentary
quote: Share with commentary

A commit without a GitMsg: trailer is a post. A post requires a trailer only when it uses a field (e.g., edits, retracted, origin fields).

1.2. Fields

Subject line requirements:

Reposts: # <Author Name> @ <owner>/<repo>: <excerpt> (remote) or # <Author Name>: <excerpt> (local)
Comments/quotes: Subject line MUST contain user content

GitMsg: trailer fields:

original: Reference to original content being commented on, reposted, or quoted
reply-to: Reference to parent comment in nested discussions

Field order: reply-to, then original.

1.3. Reference Sections

A thread is a post and the comments whose original references it.

Reference structure requirements:

Comments: original field MUST reference the thread's first post, not intermediate comments
Nested comments: MUST include both reply-to (parent comment) and original (first post) fields
Reposts: MUST reference original posts (not other reposts) using original field

1.4. Editing and Retracting

Messages MAY be edited or retracted using core versioning (GITMSG.md 1.5).

2. Lists

Lists define repositories to follow. Posts from repositories in lists appear in the timeline.

Repository entries use <url>#branch:<branch> format. #branch:* follows all branches (see GITMSG.md 2.1).

For each entry, implementations MUST read the named branch and the repository's gitmsg/social branch. On those branches, a commit without a GitMsg: trailer is a post, and a commit with a GitMsg: trailer whose ext is social is a social message.

3. Configuration

Configuration is stored at refs/gitmsg/social/config:

{
  "version": "0.1.0"
}

Configuration MUST include: version.

4. Manifest

{
  "name": "social",
  "version": "0.1.0",
  "display": "GitSocial",
  "description": "Social networking extension for GitMsg",
  "types": ["post", "comment", "repost", "quote"],
  "fields": ["original", "reply-to"]
}

Appendix: Examples

Post

Hello world!

Comment

Great idea!

GitMsg: ext="social"; type="comment"; original="https://github.com/user/repo#commit:abc123456789@main"; v="0.1.0"
GitMsg-Ref: ext="social"; type="post"; author="Alice"; email="[email protected]"; time="2025-01-06T10:30:00Z"; ref="https://github.com/user/repo#commit:abc123456789@main"; v="0.1.0"
 > Original post content

Nested Comment

I agree!

GitMsg: ext="social"; type="comment"; reply-to="#commit:def456789abc@main"; original="#commit:abc123456789@main"; v="0.1.0"
GitMsg-Ref: ext="social"; type="comment"; author="Bob"; email="[email protected]"; time="2025-01-06T11:00:00Z"; ref="#commit:def456789abc@main"; v="0.1.0"
 > Parent comment
GitMsg-Ref: ext="social"; type="post"; author="Alice"; email="[email protected]"; time="2025-01-06T10:30:00Z"; ref="#commit:abc123456789@main"; v="0.1.0"
 > Original post

Repost

# Alice @ user/repo: Original content excerpt

GitMsg: ext="social"; type="repost"; original="https://github.com/user/repo#commit:abc123456789@main"; v="0.1.0"
GitMsg-Ref: ext="social"; type="post"; author="Alice"; email="[email protected]"; time="2025-01-06T10:30:00Z"; ref="https://github.com/user/repo#commit:abc123456789@main"; v="0.1.0"
 > Original content

Edit Post

Hello world! (updated)

GitMsg: ext="social"; type="post"; edits="#commit:abc123456789@main"; v="0.1.0"

Retract Post

GitMsg: ext="social"; edits="#commit:abc123456789@main"; retracted="true"; v="0.1.0"

Edit Comment

Great idea! I especially like the part about...

GitMsg: ext="social"; type="comment"; edits="#commit:def456789abc@main"; original="#commit:abc123456789@main"; v="0.1.0"
GitMsg-Ref: ext="social"; type="post"; author="Alice"; email="[email protected]"; time="2025-01-06T10:30:00Z"; ref="#commit:abc123456789@main"; v="0.1.0"
 > Original post content