gitlinks

Git Remote Link Resolution

Relevant source files

• src/repodocs/gitlinks.py

Overview

gitlinks.py is a small, dependency-light module responsible for turning a repository's git origin into real GitHub URLs and for rewriting markdown citation links (<a href="https://github.com/aryrabelo/repodocs/blob/51ba8b18a6abbf0ed1789af067cb1c932993f747/path#L1-L2" target="_blank" rel="noopener">text</a>) into absolute, clickable <a> tags pointing at blob/<sha> on GitHub. It is used both to compute the base URL for citation rewriting and to determine the GitHub wiki push target.

Sources: src/repodocs/gitlinks.py:L1-L21

Parsing GitHub remotes

_github_slug(url) accepts either the SSH form (git@github.com:OWNER/REPO(.git)?) or the HTTPS form (https?://github.com/OWNER/REPO(.git)?/?) and extracts owner and repo via two alternative regexes. It returns None if neither pattern matches.

Sources: src/repodocs/gitlinks.py:L24-L35

Both extracted segments are validated against _SLUG_PART (^[A-Za-z0-9._-]+$) before being accepted. Real GitHub owner/repo names are restricted to this character set, so anything else indicates the parsed remote isn't a genuine GitHub path. This check exists specifically to stop HTML/attribute metacharacters (quotes, angle brackets) from a malformed remote URL from flowing into a generated citation href later in rewrite_citation_links().

Sources: src/repodocs/gitlinks.py:L17-L21, src/repodocs/gitlinks.py:L32-L35

Computing the wiki remote URL

wiki_remote_url(origin_url) reuses _github_slug to derive owner/repo, then reconstructs a <owner>/<repo>.wiki.git clone URL in the same scheme (SSH or HTTPS) as the input. If the origin doesn't parse as GitHub, it returns None.

Sources: src/repodocs/gitlinks.py:L38-L46

Computing the citation base URL

github_base(repo) shells out to git -C <repo> remote get-url origin and git -C <repo> rev-parse HEAD, parses the origin with _github_slug, and validates the SHA against ^[0-9a-f]{7,40}$. If both checks pass it returns https://github.com/<owner>/<repo>/blob/<sha>; otherwise None. Subprocess failures (OSError, FileNotFoundError) are caught and also yield None.

Sources: src/repodocs/gitlinks.py:L49-L61

Verifying citations are honest: citations_safe

Because github_base points at a specific commit SHA, a citation link is only truthful if that SHA's tree matches what's actually on disk and has been pushed to the remote. citations_safe(porcelain, remote_contains, out_rel=None) enforces this:

• It walks the lines of git status --porcelain output (porcelain) and treats any non-empty line as "dirty" unless it is an untracked (??) entry that falls under out_rel, the repodocs output directory. Freshly generated wiki pages are expected to be untracked and are excluded from the dirty check via _is_output; any other untracked path could be the very file a citation targets, so it counts as dirty.
• Without out_rel supplied, every untracked entry counts as dirty (fail-safe default).
• If any dirty lines remain, it returns (False, "working tree dirty").
• If remote_contains (typically the output of a git branch --contains-style check against the remote) is empty, it returns (False, "HEAD not pushed").
• Otherwise it returns (True, None).

Sources: src/repodocs/gitlinks.py:L64-L81

Rewriting citation links into GitHub blob URLs

rewrite_citation_links(md, base) scans the markdown for citation-style links using _MD_LINK (\[([^\]]+)\]\(([^)]+)\)) and, for each match, validates the href against _CITE_HREF:

^(?!https?://)([^#)]+)#L(\d+)(?:-L(\d+))?$

This requires the href to be a relative path (not already an absolute http(s):// link) followed by #L<start> and an optional -L<end>. Links that don't match this shape (e.g. already-absolute URLs) are left untouched.

Sources: src/repodocs/gitlinks.py:L11-L14, src/repodocs/gitlinks.py:L91-L104

For matching links, the function rebuilds the anchor (#L<a> or #L<a>-L<b>), HTML-escapes both base and the link text (html.escape(..., quote=True)), URL-quotes the path (urllib.parse.quote(path, safe="/")), and emits:

<a href="{safe_base}/{safe_path}{anchor}" target="_blank" rel="noopener">{safe_text}</a>

If base is falsy (e.g. github_base returned None), the function returns md unchanged, leaving citations as plain relative markdown links rather than rewriting them to broken or misleading URLs.

Sources: src/repodocs/gitlinks.py:L91-L109

The combination of _SLUG_PART validation in _github_slug and the html.escape/urllib.parse.quote calls here means that even if base or a citation path originates from untrusted LLM-authored markdown, no HTML tag or attribute injection can occur in the emitted <a> element.

Sources: src/repodocs/gitlinks.py:L17-L21, src/repodocs/gitlinks.py:L92-L108

End-to-end flow

Sources: src/repodocs/gitlinks.py:L49-L109