A free tool turns a Go repository into one HTML map you can hand to someone
Peter Retief’s repository map favors a file you can pass around, while its documented exclusions define what the picture leaves out.
A repository tour can arrive as one HTML file. Codemap generates a navigable picture of a Go module, so the person receiving it can start exploring without bringing up another documentation service. One less server to keep warm is already a pleasant introduction.
Peter Retief’s project documentation describes packages arranged around their internal dependencies, with files and functions available inside them. Selecting a package reveals what it uses and what uses it. For a module on GitHub, function links can jump to the corresponding source line.
The output is a single page that can be opened in a browser or put on a website. The README says there is “nothing to serve.” It also discloses a Google Fonts request with system-font fallback, so one file should not be expanded into a claim of absolutely no external request under every setting.
Its arrangement has a specific meaning: a row builds on rows below it. Wider boxes represent more functions, and top-level folders determine colors. That gives the image a reading direction rather than merely dropping names onto a diagram and hoping somebody enjoys untangling spaghetti.
The exclusions matter as much as the layout. Tests, vendor content, testdata and folders with their own go.mod are left out. A reader seeking the complete test strategy or every nested module needs another route. A map can be accurate about the territory it chooses while remaining very selective about the rest.
The maker reports checking package, file and function counts against plain-text counts for several projects, including Kubernetes. The documented Kubernetes example has 1,278 packages and 34,823 functions, takes under two seconds, and produces a 4.5 MB page. Those figures describe the maker’s reported exercise; they do not guarantee the same time on your laptop.
For someone inheriting a Go service, a sensible first use would be to select a familiar entry package and follow its immediate dependencies. That tests the map’s practical readability against a path someone understands. A complete inventory can still make a terrible welcome packet if nobody can find the front door.
Sharing the generated file also means sharing its contents. A private codebase may reveal internal package names and function structure through the map even without copying every source file. The appropriate audience is therefore part of the handoff decision, rather than a surprise after the HTML has been attached to a public ticket.
The project requires Go 1.24 or later for the documented command. That requirement belongs before the command in any onboarding note. Otherwise a tool meant to simplify a repository tour begins with everyone troubleshooting the tour guide’s shoes.
A generated map could become a useful companion to a review or release if it travels with the revision it describes. Stale diagrams have excellent manners until someone follows them into a deleted hallway. Codemap supplies the artifact; deciding which source revision it represents remains part of the handoff.
Your code has a floor plan.