{"id":15048124,"url":"https://github.com/github/code-navigation","last_synced_at":"2025-08-02T12:33:51.482Z","repository":{"id":245306801,"uuid":"801788004","full_name":"github/code-navigation","owner":"github","description":"Public documentation about GitHub's code navigation system","archived":false,"fork":false,"pushed_at":"2025-03-19T17:45:13.000Z","size":32,"stargazers_count":6,"open_issues_count":2,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-27T06:25:49.792Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.github.com/en/repositories/working-with-files/using-files/navigating-code-on-github","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/github.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-16T23:15:15.000Z","updated_at":"2025-04-01T21:13:05.000Z","dependencies_parsed_at":"2024-06-21T09:25:01.423Z","dependency_job_id":"2fed7c51-7a0b-45fe-b146-50c4feb58197","html_url":"https://github.com/github/code-navigation","commit_stats":null,"previous_names":["github/code-navigation"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/github/code-navigation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fcode-navigation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fcode-navigation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fcode-navigation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fcode-navigation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/github","download_url":"https://codeload.github.com/github/code-navigation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fcode-navigation/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268389105,"owners_count":24242726,"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","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-09-24T21:08:25.457Z","updated_at":"2025-08-02T12:33:51.466Z","avatar_url":"https://github.com/github.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub code navigation\n\nGitHub code navigation helps you to read, navigate, and understand code by linking definitions of named symbols (like a class or method) to references to that symbol, as well as linking references to the symbol's definition. GitHub code navigation uses code search to find all definitions and references across a repository to find symbols with a given name.\n\nCode navigation is implemented using the [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) parser ecosystem.\n\nFor more information, see \"[Navigating code on GitHub](https://docs.github.com/en/repositories/working-with-files/using-files/navigating-code-on-github).\"\n\n## Supported languages\n\nCode navigation is supported for the following languages:\n\n- Bash\n- C#\n- C++\n- CodeQL\n- Elixir\n- Go\n- JSX\n- Java\n- JavaScript\n- Lua\n- PHP\n- Protocol Buffers\n- Python\n- R\n- Ruby\n- Rust\n- Scala\n- Starlark\n- Swift\n- Typescript\n\nIf your programming language is not one of them, you can help us add it.\n\n## Adding code navigation for a new language\n\nTo add code navigation for a new language, you must follow these steps:\n\n1. Add the language to Linguist.\n2. Define a Tree-sitter parser for the language.\n3. Write tags queries.\n4. Write fully-qualified name queries (if applicable).\n5. Open an issue in this repository.\n\nFor details, see below.\n\n\u003e [!NOTE]\n\u003e Adding a language is at the discretion of GitHub. We may not add every language. Common reasons to reject language support include an immature Tree-sitter parser, excessive resources required to parse, or low use on GitHub.\n\n### Add the language to Linguist\n\nFirst, the language must be added to [Linguist](https://github.com/github-linguist/linguist). Linguist is the source of truth for all languages on GitHub.\n\n You can check to see if the language exists in Linguist by searching the [`languages.yml`](https://github.com/github-linguist/linguist/blob/master/lib/linguist/languages.yml) file. If your language is not included in Linguist, [follow the contribution guidelines](https://github.com/github-linguist/linguist/blob/master/CONTRIBUTING.md#adding-a-language) to get it added.\n\n### Tree-sitter parser\n\nNext, we require a mature, well-maintained Tree-sitter parser for the language. The parser must publish a Rust crate to [crates.io](https://crates.io/).\n\nMost popular programming languages already have a Tree-sitter grammar, but if you need to create one, you can [review the documentation for creating a new parser](https://tree-sitter.github.io/tree-sitter/creating-parsers).\n\n### Tags query\n\nOnce the language has a Tree-sitter parser, you need to write _tag queries_ to extract the structure of the code for navigation. A tag query is a Scheme-like expression that navigates the Abstract Syntax Tree generated by the Tree-sitter parser to extract a symbol. You can look at existing Tree-sitter parsers for inspiration. Parsers usually contain a file called `tags.scm` with tag queries (for example, [see the JavaScript tag queries](https://github.com/tree-sitter/tree-sitter-javascript/blob/master/queries/tags.scm)). Additionally, Tree-sitter has documentation about [using tags queries for code navigation](https://tree-sitter.github.io/tree-sitter/4-code-navigation.html).\n\nGitHub code navigation supports extracting definitions for these types of symbols:\n\n| Category       | Tag                          |\n|----------------|------------------------------|\n| Class          | `@definition.class`          |\n| Constant       | `@definition.constant`       |\n| Enum           | `@definition.enum`           |\n| Enum variant   | `@definition.enum_variant`   |\n| Field          | `@definition.field`          |\n| Function       | `@definition.function`       |\n| Implementation | `@definition.implementation` |\n| Interface      | `@definition.interface`      |\n| Macro          | `@definition.macro`          |\n| Method         | `@definition.method`         |\n| Module         | `@definition.module`         |\n| Struct         | `@definition.struct`         |\n| Trait          | `@definition.trait`          |\n| Type           | `@definition.type`           |\n| Union          | `@definition.union`          |\n\nAdditionally, references to function or method calls can be extracted as `@reference.call`.\n\nNot all programming languages support all of these symbol types. The tag queries should contain only those that make sense for your programming language.\n\n### Fully-qualified names\n\nFor languages that support defining functions, methods, or other entities within another structure, GitHub code navigation supports extracting fully-qualified names. Fully-qualified names are used to improve code navigation as well as the relevance of search results.\n\nHere is an example from our Java extractor. The following Java code defines a class named `Cat` that has a method named `noise`:\n\n```java\npublic class Cat {\n  public String noise() {\n    return \"meow\";\n  }\n}\n```\n\nOur tag queries extract `@definition.class` and `@definition.method` and tag the identifiers with `@name`:\n\n```scheme\n(class_declaration name: (identifier) @name) @definition.class\n\n(method_declaration name: (identifier) @name) @definition.method\n```\n\nThe extracted identifier names are used to prefix the method name (`noise`) with its container's name (`Cat`), resulting in the fully-qualified name `Cat::noise`.\n\nHowever, not all languages define nested items within the container. For example, Go has methods, but they are defined separately from the struct they belong to:\n\n```go\ntype Cat struct {}\n\nfunc (c Cat) Noise() string {\n    return \"meow\"\n}\n```\n\nTo implement fully-qualified names for languages like Go, GitHub code navigation adds a `@scope` capture name:\n\n```scheme\n(method_declaration\n  receiver: (parameter_list (parameter_declaration type: (type_identifier) @scope))\n  name: (field_identifier) @name\n) @definition.method\n```\n\nOur extractor uses the `@scope` capture to create the fully qualified name `Cat.Noise`.\n\nIf your language supports nested entities that are defined separately, include a `@scope` capture for best results with GitHub code navigation.\n\n### File a request to add your language\n\nFinally, [create an issue in this repository](https://github.com/github/code-navigation/issues/new?template=language-support-request.md). We will evaluate adding the parser to the code search indexing system.\n\n## License\n\nThis project is licensed under the terms of the MIT open source license. Please refer to [the license](./LICENSE.txt) for the full terms.\n\n## Maintainers\n\nThis project is maintained by members of the GitHub code search team.\n\n## Support\n\nPlease file an issue for support. See [SUPPORT.md](./SUPPORT.md) for details.\n\n## Acknowledgments\n\nGitHub code navigation is made possible by the [Tree-sitter](https://tree-sitter.github.io/) ecosystem and all the Tree-sitter parser maintainers. Thank you!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fcode-navigation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgithub%2Fcode-navigation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fcode-navigation/lists"}