Social Extension

Posts, comments, reposts and quotes are commits (GITSOCIAL.md), written to the gitmsg/social branch unless init names another. The timeline is the union of the lists a workspace follows.

Initialize · Post · Blog · Lists and timeline · Followers · Reference

Initialize

gitsocial social init [-b <branch>]
gitsocial social config get|set|list

init is idempotent. It creates refs/gitmsg/social/config and the gitmsg/social branch. -b names the branch that post, comment, repost and quote write to.

On each branch that the timeline reads, a commit without a GitMsg: trailer is a post, so a plain git commit is also a post. Commits with a trailer are comments, reposts, quotes, edits or retractions.

Post

gitsocial social post "Hello world" [-l kind/note]
gitsocial social comment <ref> "Great idea!"
gitsocial social repost <ref>
gitsocial social quote <ref> "Worth reading:"
gitsocial social edit <ref> "Updated text"
gitsocial social retract <ref>

The original of a comment is the root post of the thread, and a nested reply adds reply-to for its parent. Edits and retractions use core versioning, and the latest version has priority.

Blog

A blog uses one branch and has no gitmsg/social branch.

gitsocial social init -b main
git commit -m "Hello world"                 # a plain commit on main is a post
gitsocial social post "A shorter note"
gitsocial social edit <ref> "Updated text"
gitsocial social retract <ref>

edit and retract write to the branch that the post is on; for a blog, this is main. A follower names that branch with list add -b main, or lets list add record the repository's default branch.

Lists and timeline

A list is a named set of repositories. The timeline shows posts from every list, or from one list with -l.

gitsocial social list create following
gitsocial social list add following https://github.com/user/repo [-b <branch> | --all-branches]
gitsocial social list remove following https://github.com/user/repo
gitsocial social list show [following]
gitsocial social list ls
gitsocial social list delete following
gitsocial social list repo <repo-url>       # the lists a remote repository publishes
gitsocial social timeline [-l following] [-r workspace] [-n 50]
gitsocial social fetch                      # every repository in every list; `gitsocial fetch` does this and more

list add fetches the URL that you type; list remove accepts each form of it, because GitSocial compares URLs by identity. A repository is in a list one time, on one branch or on all branches. The timeline reads the branch that the member names, the gitmsg/social branch of the repository, and all branches of the workspace.

In the TUI, the Repository view reads all branches of a repository unless a branch is picked. My Branches in the navigation, or b on a repository, lists the branches with their commit counts, and Enter opens one (TUI-KEYS.md). c on a repository or a branch opens its code: the tree of the branch, and each file with line numbers (TUI-KEYS.md). My Tags, or t, lists the tags of the local clone with the commits since the previous tag, and Enter opens the release that names a tag (TUI-KEYS.md). w on My Repository shows the working tree: s and u stage and unstage a file, and C commits the index with a subject and a body (TUI-KEYS.md).

Followers

A repository follows the workspace when one of its lists contains the workspace URL. GitSocial finds followers during a fetch.

gitsocial social followers [--json]

Reference

• Where social messages are stored is specified in GITMSG.md §3.4.
• Lists are at refs/gitmsg/social/lists/<name>/, one ref per member and metadata at _meta (ARCHITECTURE.md).
• The timeline excludes retracted posts (GITMSG.md §1.5) and stale commits (ARCHITECTURE.md). It sorts by effective timestamp, newest first, and imported content sorts by its origin time.
• The timeline shows an action as an entry of one line at the time of the action; see Timeline actions.
• The comment, repost and quote counts of a card include only the items that are not retracted, so retracting a comment decreases the comment count.
• A comment names the branch that its commit was on. After a merge moves the commit to another branch, its thread and its counts follow the commit, and a new comment names the branch that the commit is on now (ARCHITECTURE.md).
• gitsocial social log lists an item by its own type: a comment on a post is a comment, not a post.
• Mentions, replies, comments and reposts of workspace posts create notifications.
• In the TUI, S opens the timeline (TUI-KEYS.md).

Timeline actions

An action is derived from commits that exist already: an edit that changes a state, or a review. No command writes an action.

Action	Shown for	Source
closed, reopened, canceled	issue, milestone, sprint	an edit whose state differs from the version before it
started, completed	sprint	an edit that changes state to active or completed
merged, closed, reopened	pull request	an edit whose state differs from the version before it
ready	pull request	an edit that removes draft="true" from an open pull request
approved, changes-requested	pull request	a review with review-state; an edit of the review only when the value changes

• The version before an edit is the earlier version of the same repository by commit time, then by hash.
• An edit of text, labels or assignees, a retraction, an edit from another repository and a conversion to draft are not actions.
• A merge that closes issues shows one entry that names them. The closed entry of an issue is hidden when the same author merged a pull request that closes it not more than 60 seconds before.
• Only the timeline shows an action entry, for all lists or for one list (-l). Issue, pull request and repository lists show items only, and a review shows there with its full text.
• When two versions of an item have the same commit time, the TUI orders them by hash and the site by history, so the two can name the action on different edits.
• The site derives an action only when the first version of the item is in the part of the history that the browser has loaded. Before that, it shows the edit as an item card.