Skip to main content
The init command sets up Graph-sitter in your repository, creating necessary configuration files and pulling documentation locally.

​
Usage

gs init [OPTIONS]

​
Options

  • --repo-name: The name of the repository (defaults to current git repo name)
  • --organization-name: The name of the organization (defaults to git organization)

​
Directory Structure

When you run init, gs creates a .codegen directory in your repository with the following structure: 
.codegen/
├── config.toml         # Configuration file with repo and org info
├── codemods/          # Your codemods live here
│   └── my_codemod.py  # Created via `gs create my-codemod`
├── docs/              # Local documentation for offline access
│   ├── api/
│   ├── examples/
│   └── tutorials/
└── prompts/           # Generated system prompts for AI assistance
Only config.toml and the codemods/ directory are tracked in Git. The rest of the .codegen directory is automatically added to your .gitignore.
This setup allows you to:
  • Track and version your codemods with your repository
  • Use codebase.reset() without losing progress on your codemod implementation
  • Share codemods with your team through version control
We recommend keeping your Graph-sitter codemods in the .codegen/codemods/ directory (this is the default when using gs create). This:
  • Keeps transformation code separate from your application code
  • Makes it easy to find and manage all your codemods
  • Ensures consistent behavior with codebase.reset()

​
Local Documentation

Graph-sitter pulls documentation and examples locally to:
  • Provide offline access to guides and references
  • Enable AI to give contextual help about your codebase
  • Allow searching through examples and tutorials

​
Requirements

The command must be run from within a git repository. If you’re not in one, you’ll need to: 
git init
git remote add origin <your-repo-url>
gs init

​
Examples

Initialize with default settings (uses git repo info): 
gs init
Initialize with custom organization and repo: 
gs init --organization-name "my-org" --repo-name "my-project"

​
Next Steps

After initializing:
  1. Create your first codemod:
gs create my-function . -d "describe what you want to do"
Note: The second parameter (.) specifies the path where the codemod should be created. This is required.
  1. Run it:
gs run my-function --apply-local

​
Updating

You can run init again to update your local documentation and configuration: 
gs init
This will refresh the .codegen directory while preserving your existing configuration.