init

Initialize a grammar repository

The init command is your starting point for creating a new grammar. It sets up a repository with all the essential files and structure needed for grammar development.

tree-sitter init [OPTIONS]

Aliases: i

Since the command includes git-related files by default, we recommend using git for version control of your grammar.

Generated Files

Required Files

These files are always created if missing:

tree-sitter.json

The main configuration file that determines how tree-sitter interacts with the grammar. If missing, the command will prompt you for the required fields. See Structure of tree-sitter.json below.

package.json

The npm manifest for the parser. Required for some subcommands and if the grammar has dependencies (e.g., base grammars).

grammar.js

An empty template for the main grammar file. See Creating Parsers.

Language Bindings

Language bindings allow your parser to be used by projects in the respective language. The following bindings are created if enabled in tree-sitter.json:

C/C++

• Makefile - Build instructions for make
• CMakeLists.txt - Build instructions for cmake
• bindings/c/tree_sitter/tree-sitter-language.h - C interface
• bindings/c/tree-sitter-language.pc - pkg-config metadata

Go

• go.mod - Go module manifest
• bindings/go/binding.go - Go module wrapper
• bindings/go/binding_test.go - Go package test

Node

• binding.gyp - Node.js build instructions
• bindings/node/binding.cc - JavaScript module wrapper
• bindings/node/index.js - Node.js entry point
• bindings/node/index.d.ts - TypeScript type hints
• bindings/node/binding_test.js - Node.js package test

Java

• pom.xml - Maven package manifest
• bindings/java/main/namespace/language/TreeSitterLanguage.java - Java class wrapper
• bindings/java/test/TreeSitterLanguageTest.java - Java package test

Python

• pyproject.toml - Python package manifest
• setup.py - Python build instructions
• bindings/python/tree_sitter_language/binding.c - Python module wrapper
• bindings/python/tree_sitter_language/__init__.py - Python loader
• bindings/python/tree_sitter_language/__init__.pyi - Type hints
• bindings/python/tree_sitter_language/py.typed - Type hints marker
• bindings/python/tests/test_binding.py - Python package test

Rust

• Cargo.toml - Rust package manifest
• bindings/rust/build.rs - Rust build instructions
• bindings/rust/lib.rs - Rust crate wrapper

Swift

• Package.swift - Swift build instructions
• bindings/swift/TreeSitterLanguage/language.h - Swift module wrapper
• bindings/swift/TreeSitterLanguageTests/TreeSitterLanguageTests.swift - Swift package test

Zig

• build.zig - Zig build instructions
• build.zig.zon - Zig package manifest
• bindings/zig/root.zig - Zig module wrapper
• bindings/zig/test.zig - Zig package test

Additional Files

These files improve the development experience:

• .editorconfig - Editor formatting configuration
• .gitattributes - Git line endings and language attribution
• .gitignore - Git ignore patterns

Structure of tree-sitter.json

grammars Field

An array of grammar objects. Typically only one object is needed unless your repo has multiple grammars (e.g., TypeScript and TSX).

{
  "grammars": [
    {
      "name": "ruby",
      "scope": "source.ruby",
      "file-types": ["rb", "gemspec", "Gemfile", "Rakefile"],
      "first-line-regex": "#!.*\\bruby$"
    }
  ]
}

Basic Fields

scope · string · required

A string like "source.js" that identifies the language. Strive to match scope names used by popular TextMate grammars and the Linguist library.

path · string

Relative path from tree-sitter.json to the directory containing src/. Default is "." (same folder).

external-files · array

List of relative paths to files that should be checked for modifications during recompilation. Useful for tracking changes to files like scanner.c.

Language Detection

file-types · array

Filename suffix strings (without the dot) that identify files for this language. Suffixes may match entire filenames.

first-line-regex · string

Regex pattern tested against the first line of a file. Used when file type doesn’t match any grammar’s file-types.

content-regex · string

Regex pattern tested against file contents to break ties when multiple grammars match. Grammars with matching content-regex are preferred.

injection-regex · string

Regex pattern tested against a language name for language injection sites. See Language Injection.

Query Paths

Relative paths from tree-sitter.json to query files:

highlights · string · default: "queries/highlights.scm"

Path to highlight query file.

locals · string · default: "queries/locals.scm"

Path to local variable query file.

injections · string · default: "queries/injections.scm"

Path to injection query file.

tags · string · default: "queries/tags.scm"

Path to tag query file.

metadata Field

Information used to populate binding files and versions:

version · string · required

Current version following semver.

license · string

Valid SPDX license identifier.

description · string

Brief description of your grammar.

authors · array · required

Array of objects with name (required), email, and url fields.

links · object

Object with repository field and optional funding field.

namespace · string · default: "io.github.tree-sitter"

Namespace for Java and Kotlin bindings.

bindings Field

Controls which bindings are generated:

c · boolean · default: true

Generate C/C++ bindings.

go · boolean · default: true

Generate Go bindings.

java · boolean · default: false

Generate Java bindings.

node · boolean · default: true

Generate Node.js bindings.

python · boolean · default: true

Generate Python bindings.

rust · boolean · default: true

Generate Rust bindings.

swift · boolean · default: false

Generate Swift bindings.

zig · boolean · default: false

Generate Zig bindings.

Options

-u, --update · flag

Update outdated generated files, if possible. Existing files that may have been edited manually are not updated. To force an update, remove them and run tree-sitter init -u again.

-p, --grammar-path · path

The path to the directory containing the grammar.