diff --git a/34.md b/34.md index ab80a936..7a3ccc0f 100644 --- a/34.md +++ b/34.md @@ -165,6 +165,81 @@ The most recent Status event (by `created_at` date) from either the issue/patch The 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. +## Git Diffs + +Git Diff events (`kind: 1622`) represent changes between two commits within a Git repository, encapsulated as a unified diff. This event type is distinct from Git patches as it explicitly represents the state difference between two specific commits rather than modifications intended for direct application. + +Clients should render the event's `content` field as preformatted unified diff text (commonly displayed with diff highlighting). + +```jsonc +{ + "kind": 1622, + "content": "", + "tags": [ + // Reference to the repo's 30617 event if one exists + ["a", "30617::"], + // Explicit commit ID this diff represents (mandatory) + ["commit", ""], + // Parent commit ID from which the diff is generated (mandatory) + ["parent-commit", ""], + + // Explicit repository URL (optional if resolvable via 'a' tag, recommended for interoperability) + ["repo", "https://github.com/user/repo.git"], + // refs associated with the repository + ["refs//",""] + // File path within the repository affected by this diff (optional but recommended if diff is single-file) + ["file", ""], + // Optional start and end lines in the diff context (recommended for precise referencing) + ["lines", "172", "196"], + // Optional description for context or explanation of changes + ["description", "Implements new diff handling in NIP-34"] + ] +} +``` + +Clients rendering Git Diff events SHOULD: + +- Display the unified diff content with syntax highlighting for added/removed lines. +- Provide options to view or open the diff context within external repository browsers or local Git clients. +- Use commit and parent-commit identifiers for querying or fetching the exact commit state. +- Clearly indicate repository, branch, and file context if provided. + +This detailed structure improves clarity, usability, and interoperability, providing clients with comprehensive context and ensuring precise referencing and rendering. + +## Permalinks + +Permalink events (`kind: 1623`) represent a permanent reference to specific lines within a file from a Git repository. They are intended to directly reference code or documentation precisely and immutably. Clients should render the event's `content` field as preformatted text (code blocks). + +```jsonc +{ + "kind": 1623, + "content": "", + "tags": [ + // Reference to the repo's 30617 event if one exists + ["a", "30617::"], + // Explicit repository URL (optional if resolvable via 'a' tag, recommended for interoperability) + ["repo", ""], + // refs associated with the repository (mandatory) + ["refs//",""] + // Specific commit identifier referencing the repository state (mandatory) + ["commit", ""], + // Path to the specific file in the repository (mandatory) + ["file", ""], + + // Start and end lines referenced within the file (optional, otherwise the event refers to the complete file) + ["lines", "", ""], + // Language identifier for syntax highlighting (optional but recommended) + ["l", ""], + ["description", ""] + ] +} +``` + +Clients rendering permalink events SHOULD: + +- Fetch and display the exact lines from the referenced commit and file if the content is not explicitly included or for verification. +- Display provided code/text using syntax highlighting according to the specified language tag (`l`). +- Offer navigation or direct links to view the file within external repository browsers or clients. ## Possible things to be added later