https://github.com/github/code-navigation
Public documentation about GitHub's code navigation system
https://github.com/github/code-navigation
Last synced: 10 months ago
JSON representation
Public documentation about GitHub's code navigation system
- Host: GitHub
- URL: https://github.com/github/code-navigation
- Owner: github
- License: mit
- Created: 2024-05-16T23:15:15.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-19T17:45:13.000Z (about 1 year ago)
- Last Synced: 2025-07-27T06:25:49.792Z (11 months ago)
- Homepage: https://docs.github.com/en/repositories/working-with-files/using-files/navigating-code-on-github
- Size: 31.3 KB
- Stars: 6
- Watchers: 1
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Codeowners: CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
Awesome Lists containing this project
README
# GitHub code navigation
GitHub 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.
Code navigation is implemented using the [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) parser ecosystem.
For more information, see "[Navigating code on GitHub](https://docs.github.com/en/repositories/working-with-files/using-files/navigating-code-on-github)."
## Supported languages
Code navigation is supported for the following languages:
- Bash
- C#
- C++
- CodeQL
- Elixir
- Go
- JSX
- Java
- JavaScript
- Lua
- PHP
- Protocol Buffers
- Python
- R
- Ruby
- Rust
- Scala
- Starlark
- Swift
- Typescript
If your programming language is not one of them, you can help us add it.
## Adding code navigation for a new language
To add code navigation for a new language, you must follow these steps:
1. Add the language to Linguist.
2. Define a Tree-sitter parser for the language.
3. Write tags queries.
4. Write fully-qualified name queries (if applicable).
5. Open an issue in this repository.
For details, see below.
> [!NOTE]
> 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.
### Add the language to Linguist
First, the language must be added to [Linguist](https://github.com/github-linguist/linguist). Linguist is the source of truth for all languages on GitHub.
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.
### Tree-sitter parser
Next, 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/).
Most 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).
### Tags query
Once 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).
GitHub code navigation supports extracting definitions for these types of symbols:
| Category | Tag |
|----------------|------------------------------|
| Class | `@definition.class` |
| Constant | `@definition.constant` |
| Enum | `@definition.enum` |
| Enum variant | `@definition.enum_variant` |
| Field | `@definition.field` |
| Function | `@definition.function` |
| Implementation | `@definition.implementation` |
| Interface | `@definition.interface` |
| Macro | `@definition.macro` |
| Method | `@definition.method` |
| Module | `@definition.module` |
| Struct | `@definition.struct` |
| Trait | `@definition.trait` |
| Type | `@definition.type` |
| Union | `@definition.union` |
Additionally, references to function or method calls can be extracted as `@reference.call`.
Not all programming languages support all of these symbol types. The tag queries should contain only those that make sense for your programming language.
### Fully-qualified names
For 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.
Here is an example from our Java extractor. The following Java code defines a class named `Cat` that has a method named `noise`:
```java
public class Cat {
public String noise() {
return "meow";
}
}
```
Our tag queries extract `@definition.class` and `@definition.method` and tag the identifiers with `@name`:
```scheme
(class_declaration name: (identifier) @name) @definition.class
(method_declaration name: (identifier) @name) @definition.method
```
The 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`.
However, 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:
```go
type Cat struct {}
func (c Cat) Noise() string {
return "meow"
}
```
To implement fully-qualified names for languages like Go, GitHub code navigation adds a `@scope` capture name:
```scheme
(method_declaration
receiver: (parameter_list (parameter_declaration type: (type_identifier) @scope))
name: (field_identifier) @name
) @definition.method
```
Our extractor uses the `@scope` capture to create the fully qualified name `Cat.Noise`.
If your language supports nested entities that are defined separately, include a `@scope` capture for best results with GitHub code navigation.
### File a request to add your language
Finally, [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.
## License
This project is licensed under the terms of the MIT open source license. Please refer to [the license](./LICENSE.txt) for the full terms.
## Maintainers
This project is maintained by members of the GitHub code search team.
## Support
Please file an issue for support. See [SUPPORT.md](./SUPPORT.md) for details.
## Acknowledgments
GitHub code navigation is made possible by the [Tree-sitter](https://tree-sitter.github.io/) ecosystem and all the Tree-sitter parser maintainers. Thank you!