{"id":21476961,"url":"https://github.com/adamslevy/go-doc","last_synced_at":"2026-05-18T22:06:03.826Z","repository":{"id":259161390,"uuid":"572430911","full_name":"AdamSLevy/go-doc","owner":"AdamSLevy","description":"Drop-in replacement for go doc, with completion, for Zsh power users","archived":false,"fork":false,"pushed_at":"2024-11-03T22:55:13.000Z","size":62827,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-08T21:14:16.051Z","etag":null,"topics":["go","go-doc","godoc","godocc","golang","oh-my-zsh","oh-my-zsh-plugin","zsh","zsh-completion","zsh-plugin"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AdamSLevy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.golang","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-30T09:02:04.000Z","updated_at":"2024-11-08T05:44:42.000Z","dependencies_parsed_at":"2024-10-23T09:21:02.910Z","dependency_job_id":null,"html_url":"https://github.com/AdamSLevy/go-doc","commit_stats":null,"previous_names":["adamslevy/go-doc"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdamSLevy%2Fgo-doc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdamSLevy%2Fgo-doc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdamSLevy%2Fgo-doc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdamSLevy%2Fgo-doc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AdamSLevy","download_url":"https://codeload.github.com/AdamSLevy/go-doc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243997126,"owners_count":20380981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","go-doc","godoc","godocc","golang","oh-my-zsh","oh-my-zsh-plugin","zsh","zsh-completion","zsh-plugin"],"created_at":"2024-11-23T11:11:22.897Z","updated_at":"2026-05-18T22:06:03.770Z","avatar_url":"https://github.com/AdamSLevy.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `go doc` Improved, with Zsh Completion\n\nThis is a drop in replacement for `go doc` with a number of key improvements:\n\n - Golang aware Zsh completion for symbols and packages.\n - Flags can go anywhere, not just before the normal arguments.\n - Show the imports for referenced external packages.\n - Show the file and line locations of symbols.\n - Open the file for a symbol.\n - Pager support.\n - Color output with syntax highlighting.\n\n![demo](./assets/term.gif)\n\n## Key Features\n- Advanced Zsh completion of go doc arguments, with package and symbol\n  descriptions. This also improves on existing completion for all other go\n  subcommands. Note: Bash is not supported, and is not a current goal.\n- Colorized output with syntax highlighting for modern terminal emulators with\n  `-fmt=term` or `GODOC_FORMAT=term`. A few other output modes can also be used\n  including markdown and html. See the -fmt flag.\n- More flexible argument parsing. \n  - Flags can be placed anywhere, including after and between non-flag\n    arguments. \n  - Three arguments are interpretted as `go doc \u003cpkg\u003e \u003ctype\u003e.\u003cmethod|field\u003e`.\n- Imports for external symbols which are referenced in the displayed\n  documentation are shown at the top. Stdlib imports are omitted by default but\n  can be included with `-stdlib`. Imports can be omitted with the `-no-imports`\n  flag. This is very useful when dealing with overloaded package names.\n- The path to the file and line of a requested symbol is shown as a comment\n  below the rendered symbol. This can be omitted with `-no-location`.\n- If the `-open` flag is set, instead of showing the docs, the file containing\n  a requested symbol is opened using EDITOR.\n\n\n### Key Completion Features\n\n- Complete packages and symbols for go doc, and packages for other go\n  subcommands.\n- Use of completion tags provide fine grained control over completion\n  suggestions. `^Xn` cycles through the next tag.\n- Package suggestions include relative and absolute path completion limited to\n  directories containing go files.\n- Package suggestions are module aware and reflect what go doc will accept as\n  arguments.\n- Intuitive package suggestion matching allows for easily finding packages\n  without knowing their full or exact import path.\n- Package suggestions interpret the special path segment `...` to match 0 or\n  more package path segments. This is useful when you only know the start of\n  a few parts of the import path.\n- Packages with an `internal` segment are not suggested unless what the user\n  has typed specifically matches it.\n- Package and symbol suggestions are displayed with short comments.\n- Symbol suggestions are displayed and grouped as their go definition appears\n  in go doc.\n- Symbol suggestions follow go doc case insensitive matching.\n- Symbol suggestions respect go doc flags for unexported (-u) and exact case\n  symbol matching (-c).\n- Ability to parse and complete the full single argument go doc syntax: `go doc\n  path/to/pkg.\u003csym\u003e.\u003cmethod|field\u003e`\n\n## Install\n\n1. Clone the repo. Currently I don't have the vanity import path set up, so you\n   need to clone it manually.\n2. cd path/to/go-doc \u0026\u0026 make install\n3. Reload your shell.\n\nThis will run `go install` and then `go-doc -install-completion` which will\nprompt you about the three files it can install. \n\nType `?[enter]` for more info about each file. They are summarized below as\nwell.\n\nType `p[enter]` to just print the file to stdout for you to review or redirect.\n\nNote that `ZSH_CUSTOM` must be exported for the zsh completion plugin to\ninstall successfully. Usually this is at the top of your `.zshrc` if you're\nusing Oh My Zsh but just may not be exported.\n\n### Go Drop In Replacement\nIf you want to use `go-doc` as a drop in replacement for `go doc` then you need\nto install the go shim script to a directory in your PATH occuring before the\ndirectory where the official go binary is.\n\nBy default it installs it to `$HOME/bin`. It's up to you to put this at the\nfront of your PATH. \n```\nexport PATH=\"$HOME/bin:$PATH\"\n```\n\nThe go shim script will run the official go binary normally with whatever\narguments it is passed except when the first argument is `doc`, in which case\nit calls `go-doc` with the remaining arguments.\n\nIf you ever want to call the official `go doc` instead, you can add a dash as\nthe first argument before `doc`: `go - doc ...`\n\n\n### Zsh Completion\n\n#### Oh My Zsh\nIf you use Oh My Zsh, then the Zsh completion is installed to a custom plugin\ncalled `go` in `$ZSH_CUSTOM/plugins/go/`. Two files are installed: the\n`go.plugin.zsh` plugin file and the `_golang` completion script.\n\nThen you must add `go` to your list of enabled plugins.\n\n```zsh\nplugins=(\n  # ... your other plugins ...\n  go\n)\n```\n\nThe only other requirement is that `go-doc` is in your PATH, which if you have\nyour GOPATH and GOBIN set up correctly, it will be after `go install`.\n\n#### Manual\nIf you don't use Oh My Zsh then I assume you can figure out the best way to put\n`zsh/plugins/go/_golang` somewhere in your `FPATH` and know how to enable Zsh\ncompletion generally.\n\n### Recommended Zstyles\n\nTo get the most out of the completion I recommend the following zstyle options.\nYou can just run these in your terminal directly to try them out for the\ncurrent session. Put them in your .zshrc or wherever they can get loaded when\nyou open a new shell.\n\n```zsh\n# group the different type of matches under their descriptions\nzstyle ':completion:*' group-name ''\n\nzstyle ':completion:*:*:-command-:*:*' group-order alias builtins functions commands\n\nzstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}' 'r:|[._-/]=* r:|=*' 'l:|=* r:|=*'\n\nzstyle ':completion:*' accept-exact false\n\n# format descriptions, messages, and warnings\nzstyle ':completion:*:*:*:*:descriptions' format '%F{green}-- %d --%f'\nzstyle ':completion:*:messages' format ' %F{purple} -- %d --%f'\nzstyle ':completion:*:warnings' format ' %F{red}-- no matches found --%f'\n```\n\n## LICENSES\n\n### Golang (BSD)\n\nMuch of this code was forked from the official go source which is under the BSD\nlicense. The license preamble is retained in all files containing original or\nmodified source from Go. LICENSE.golang is the LICENSE file distributed with Go.\n\n### Zsh (MIT)\nThe Zsh completion script was adapted from the Zsh Users\n[zsh-completions](https://github.com/zsh-users/zsh-completions/blob/756831c818a8724f23b6c9ba08ae990854c62881/src/_golang)\nrepo. This repo is under the Zsh license, which is MIT, but the itself script\nappears to be under the Go license. In any case LICENSE.zsh contains the Zsh\nlicense.\n\n### External Vendored Go Dependencies\nAll non-Google external dependencies are MIT. Other Google dependencies are\nBSD-3. See licenses.csv for a full CSV report as generated by\n[go-licenses](https://github.com/google/go-licenses).\n\n### My code (MIT)\n\nEverything else that I wrote not directly modified from official Go source can\nbe assumed to be under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamslevy%2Fgo-doc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadamslevy%2Fgo-doc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamslevy%2Fgo-doc/lists"}