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 (implicit - no header required on configured branch)
• comment: Response to content
• repost: Share without commentary
• quote: Share with commentary

Commits without GitMsg: trailers on the configured branch (see Section 3) are implicit posts. Commits with GitMsg: trailers are explicit interactions.

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: type, edits, retracted (core fields per GITMSG.md), then reply-to, then original.

1.3. Reference Sections

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 Deleting

Messages MAY be edited or deleted using core versioning (GITMSG.md 1.5). Implementations SHOULD display an edit indicator on modified messages.

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).

3. Configuration

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

{
  "version": "0.1.0",
  "branch": "gitmsg/social"
}

Configuration MUST include: version.

Configuration SHOULD include: branch (the branch containing all GitSocial content). Default: gitmsg/social.

Branch resolution follows GITMSG.md Section 3.3. Only the resolved branch is scanned for social content. Commits without GitMsg: trailers on this branch are implicit posts. Commits with GitMsg: trailers on this branch are interactions. All other branches are ignored.

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

Implicit 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"

Delete 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