1NIP-342======34`git` stuff5-----------67`draft` `optional`89This NIP defines all the ways code collaboration using and adjacent to [`git`](https://git-scm.com/) can be done using Nostr.1011## Repository announcements1213Git repositories are hosted in Git-enabled servers, but their existence can be announced using Nostr events. By doing so the author asserts themselves as a maintainer of the primary project, unless a `u` tag is included.1415```yaml16{17 "kind": 30617,18 "content": "",19 "tags": [20 ["d", "<repo-id>"], // usually kebab-case short name21 ["name", "<human-readable project name>"],22 ["description", "brief human-readable project description>"],23 ["web", "<url for browsing>", ...], // a webpage url, if the git server being used provides such a thing24 ["clone", "<url for git-cloning>", ...], // a url to be given to `git clone` so anyone can clone it25 ["relays", "<relay-url>", ...], // relays that this repository will monitor for patches and issues26 ["r", "<earliest-unique-commit-id>", "euc"],27 ["maintainers", "<other-recognized-maintainer>", ...],28 ["u","30617:<pubkey>:<identifer>|<git-url-https-prefered>","<relay-hint>","<author-pubkey>"], // optionally indicate repository is a subordinate fork29 ["t", "<arbitrary string>"], // hashtags labelling the repository30 ]31}32```3334The tags `web`, `clone`, `relays`, `maintainers` can have multiple values.3536The `r` tag annotated with the `"euc"` marker should be the commit ID of the earliest unique commit of this repo, made to identify it among forks and group it with other repositories hosted elsewhere that may represent essentially the same project. In most cases it will be the root commit of a repository. In case of a permanent fork between two projects, then the first commit after the fork should be used.3738Except `d`, all tags are optional.3940### Nostr Clone URL format4142A `nostr://` URL can be used to reference a repository announcement in a way that is compatible with `git clone` when a [git-remote-nostr](https://git-scm.com/docs/gitremote-helpers) helper is installed:4344```45nostr://<naddr>46nostr://<npub|nip05>/<identifier>47nostr://<npub|nip05>/<relay-hint>/<identifier>48```4950Both `<relay-hint>` and `<identifier>` MUST be percent-encoded per [RFC 3986 ยง2.1](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1). `<relay-hint>` is a relay URL whose `wss://` scheme may be omitted for brevity. `<identifier>` is the `d` tag value of the kind `30617` event.5152Examples:5354```55nostr://npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/relay.ngit.dev/ngit56nostr://npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/my%20%F0%9F%9A%80%20repo57nostr://danconwaydev.com/ws%3A%2F%2Flocalhost%3A7334/my-local-only-repo58nostr://danconwaydev.com/relay.ngit.dev/ngit59```6061## Repository state announcements6263An optional source of truth for the state of branches and tags in a repository.6465```yaml66{67 "kind": 30618,68 "content": "",69 "tags": [70 ["d", "<repo-id>"], // matches the identifier in the corresponding repository announcement71 ["refs/<heads|tags>/<branch-or-tag-name>","<commit-id>"]72 ["HEAD", "ref: refs/heads/<branch-name>"]73 ]74}75```7677The `refs` tag may appear multiple times, or none.7879## Patches and Pull Requests (PRs)8081Patches and PRs can be sent by anyone to any repository. Patches and PRs to a specific repository SHOULD be sent to the relays specified in that repository's announcement event's `"relays"` tag. Patch and PR events SHOULD include an `a` tag pointing to that repository's announcement address.8283Patches SHOULD be used if each event is under 60kb, otherwise PRs SHOULD be used.8485### Patches8687Patches in a patch set SHOULD include a [NIP-10](10.md) `e` `reply` tag pointing to the previous patch.8889The first patch revision in a patch revision SHOULD include a [NIP-10](10.md) `e` `reply` to the original root patch.9091```yaml92{93 "kind": 1617,94 "content": "<patch>", // contents of <git format-patch>95 "tags": [96 ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],97 ["r", "<earliest-unique-commit-id-of-repo>"] // so clients can subscribe to all patches sent to a local git repo98 ["p", "<repository-owner>"],99 ["p", "<other-user>"], // optionally send the patch to another user to bring it to their attention100101 ["t", "root"], // omitted for additional patches in a series102 // for the first patch in a revision103 ["t", "root-revision"],104105 // optional tags for when it is desirable that the merged patch has a stable commit id106 // these fields are necessary for ensuring that the commit resulting from applying a patch107 // has the same id as it had in the proposer's machine -- all these tags can be omitted108 // if the maintainer doesn't care about these things109 ["commit", "<current-commit-id>"],110 ["r", "<current-commit-id>"] // so clients can find existing patches for a specific commit111 ["parent-commit", "<parent-commit-id>"],112 ["commit-pgp-sig", "-----BEGIN PGP SIGNATURE-----..."], // empty string for unsigned commit113 ["committer", "<name>", "<email>", "<timestamp>", "<timezone offset in minutes>"],114 ]115}116```117118The first patch in a series MAY be a cover letter in the format produced by `git format-patch`.119120### Pull Requests121122A pull request is an event that points to proposed changes in a git repository.123124```yaml125{126 "kind": 1618,127 "content": "<markdown text>",128 "tags": [129 ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],130 ["r", "<earliest-unique-commit-id-of-repo>"] // so clients can subscribe to all PRs sent to a local git repo131 ["p", "<repository-owner>"],132 ["p", "<other-user>"], // optionally send the PR to another user to bring it to their attention133134 ["subject", "<PR-subject>"],135 ["t", "<PR-label>"], // optional136 ["t", "<another-PR-label>"], // optional137138 ["c", "<current-commit-id>"], // tip of the PR branch139 ["clone", "<clone-url>", ...], // at least one git clone url where commit can be downloaded140 ["branch-name", "<branch-name>"], // optional recommended branch name141142 ["e", "<root-patch-event-id>"], // optionally indicate PR is a revision of an existing patch, which should be closed143 ["merge-base", "<commit-id>"], // optional: the most recent common ancestor with the target branch144 ]145}146```147148### Pull Request Updates149150A PR Update changes the tip of a referenced PR event.151152```yaml153{154 "kind": 1619,155 "content": "",156 "tags": [157 ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],158 ["r", "<earliest-unique-commit-id-of-repo>"] // so clients can subscribe to all PRs sent to a local git repo159 ["p", "<repository-owner>"],160 ["p", "<other-user>"], // optionally send the PR to another user to bring it to their attention161162 // NIP-22 tags163 ["E", "<pull-request-event-id>"],164 ["P", "<pull-request-author>"],165166 ["c", "<current-commit-id>"], // updated tip of PR167 ["clone", "<clone-url>", ...], // at least one git clone url where commit can be downloaded168 ["merge-base", "<commit-id>"], // optional: the most recent common ancestor with the target branch169 ]170}171```172173## Issues174175Issues are Markdown text that is just human-readable conversational threads related to the repository: bug reports, feature requests, questions or comments of any kind. Like patches, these SHOULD be sent to the relays specified in that repository's announcement event's `"relays"` tag.176177Issues may have a `subject` tag, which clients can utilize to display a header. Additionally, one or more `t` tags may be included to provide labels for the issue.178179```json180{181 "kind": 1621,182 "content": "<markdown text>",183 "tags": [184 ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],185 ["p", "<repository-owner>"]186 ["subject", "<issue-subject>"]187 ["t", "<issue-label>"]188 ["t", "<another-issue-label>"]189 ]190}191```192193## Replies194195Replies to either a `kind:1621` (_issue_), `kind:1617` (_patch_) or `kind:1618` (_pull request_) event should follow [NIP-22 comment](22.md).196197## Status198199Root Patches, PRs and Issues have a Status that defaults to 'Open' and can be set by issuing Status events.200201```yaml202{203 "kind": 1630, // Open204 "kind": 1631, // Applied / Merged for Patches; Resolved for Issues205 "kind": 1632, // Closed206 "kind": 1633, // Draft207 "content": "<markdown text>",208 "tags": [209 ["e", "<issue-or-PR-or-original-root-patch-id-hex>", "", "root"],210 ["e", "<accepted-revision-root-id-hex>", "", "reply"], // for when revisions applied211 ["p", "<repository-owner>"],212 ["p", "<root-event-author>"],213 ["p", "<revision-author>"],214215 // optional for improved subscription filter efficiency216 ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>", "<relay-url>"],217 ["r", "<earliest-unique-commit-id-of-repo>"]218219 // optional for `1631` status220 ["q", "<applied-or-merged-patch-event-id>", "<relay-url>", "<pubkey>"], // for each221 // when merged222 ["merge-commit", "<merge-commit-id>"]223 ["r", "<merge-commit-id>"]224 // when applied225 ["applied-as-commits", "<commit-id-in-master-branch>", ...]226 ["r", "<applied-commit-id>"] // for each227 ]228}229```230231The most recent Status event (by `created_at` date) from either the issue/patch author or a maintainer is considered valid.232233The Status of a patch-revision is to either that of the root-patch, or `1632` (_Closed_) if the root-patch's Status is `1631` (_Applied/Merged_) and the patch-revision isn't tagged in the `1631` (_Applied/Merged_) event.234235## User grasp list236237List of [grasp servers](https://njump.me/naddr1qvzqqqrhnypzpgqgmmc409hm4xsdd74sf68a2uyf9pwel4g9mfdg8l5244t6x4jdqy28wumn8ghj7un9d3shjtnwva5hgtnyv4mqqpt8wfshxuqlnvh8x) the user generally wishes to use for NIP-34 related activity. It is similar in function to the NIP-65 relay list and NIP-B7 blossom list.238239The event SHOULD include a list of `g` tags with grasp service websocket URLs in order of preference.240241```yaml242{243 "kind": 10317,244 "content": "",245 "tags": [246 ["g", "<grasp-service-websocket-url>"], // zero or more grasp sever urls247 ],248}249```250251## Possible things to be added later252253- inline file comments kind (we probably need one for patches and a different one for merged files)