0
# Grammar Management
1

2
Commands for initializing, configuring, and managing Tree-sitter grammar projects. These commands handle project scaffolding, configuration management, and version control for grammar development.
3

4
## Capabilities
5

6
### Configuration Initialization
7

8
Generate a default configuration file for Tree-sitter CLI with initial settings for language loading, syntax highlighting themes, and parse visualization.
9

10
```bash { .api }
11
tree-sitter init-config
12
```
13

14
Creates `~/.config/tree-sitter/config.json` with default configurations. Fails if configuration file already exists - remove existing file first to regenerate.
15

16
**Example:**
17
```bash
18
# Generate initial configuration
19
tree-sitter init-config
20

21
# Configuration created at ~/.config/tree-sitter/config.json
22
```
23

24
### Grammar Project Initialization
25

26
Initialize a new Tree-sitter grammar project with interactive setup for grammar metadata, build configuration, and project files.
27

28
```bash { .api }
29
tree-sitter init [--update]  # Alias: i
30
```
31

32
**Options:**
33
- `--update, -u`: Update outdated files in existing projects
34

35
Interactive prompts collect grammar information:
36
- **Parser name**: Lowercase name with letters, digits, underscores only
37
- **CamelCase name**: Human-readable version for displays
38
- **Title**: Human-readable project title
39
- **Description**: Grammar description
40
- **Repository URL**: Git repository location
41
- **Funding URL**: Optional funding/sponsorship URL
42
- **TextMate scope**: Language scope (must start with `source.` or `text.`)
43
- **File types**: Space-separated file extensions
44
- **Version**: Initial semver version
45
- **License**: License identifier (default: MIT)
46
- **Author details**: Name, email, URL
47

48
**Generated Files:**
49
- `tree-sitter.json`: Project configuration
50
- `grammar.js`: Grammar definition template
51
- `package.json`: npm package configuration
52
- `Cargo.toml`: Rust crate configuration (if applicable)
53
- `binding.gyp`: Node.js binding configuration
54
- `.gitignore`: Version control exclusions
55
- `README.md`: Project documentation
56

57
**Example:**
58
```bash
59
# Initialize new grammar project
60
cd my-new-language
61
tree-sitter init
62

63
# Follow interactive prompts to configure grammar
64
# Updates existing project files if already initialized
65
tree-sitter init --update
66
```
67

68
### Version Management
69

70
Increment the version number of a grammar project, updating version references across configuration files.
71

72
```bash { .api }
73
tree-sitter version <version>  # Alias: publish
74
```
75

76
**Arguments:**
77
- `<version>`: Semantic version number (e.g., "1.2.3")
78

79
Updates version in:
80
- `tree-sitter.json`
81
- `package.json`
82
- `Cargo.toml`
83
- Other relevant configuration files
84

85
**Example:**
86
```bash
87
# Bump version to 1.2.3
88
tree-sitter version 1.2.3
89

90
# Updates all configuration files with new version
91
```
92

93
## Project Structure
94

95
A typical Tree-sitter grammar project structure after initialization:
96

97
```
98
my-language/
99
├── tree-sitter.json      # Main project configuration
100
├── grammar.js            # Grammar definition
101
├── package.json          # npm package config
102
├── Cargo.toml           # Rust crate config (optional)
103
├── binding.gyp          # Node.js binding config
104
├── src/                 # Generated parser source
105
│   ├── parser.c
106
│   ├── tree_sitter/
107
│   └── ...
108
├── test/                # Test corpus
109
│   └── corpus/
110
├── queries/             # Tree-sitter queries
111
│   ├── highlights.scm
112
│   └── tags.scm
113
├── examples/            # Example files
114
├── .gitignore
115
└── README.md
116
```
117

118
## Configuration Files
119

120
### tree-sitter.json
121

122
Main project configuration file:
123

124
```json
125
{
126
  "grammars": [
127
    {
128
      "name": "my_language",
129
      "camelcase": "MyLanguage", 
130
      "scope": "source.mylang",
131
      "file-types": ["mylang", "ml"],
132
      "highlights": ["queries/highlights.scm"],
133
      "tags": ["queries/tags.scm"]
134
    }
135
  ]
136
}
137
```
138

139
### Grammar Dependencies
140

141
Grammar projects can specify dependencies on other grammars for complex language support:
142

143
```json
144
{
145
  "grammars": [
146
    {
147
      "name": "embedded_template",
148
      "dependencies": ["html", "javascript", "css"]
149
    }
150
  ]
151
}
152
```