|
| 1 | +# GitLens Copilot Instructions |
| 2 | + |
| 3 | +This workspace contains **GitLens** - a VS Code extension that supercharges Git functionality. Below are key development guidelines and architecture insights. |
| 4 | + |
| 5 | +## Core Commands |
| 6 | + |
| 7 | +### Build & Development |
| 8 | + |
| 9 | +- `pnpm run build` - Full development build |
| 10 | +- `pnpm run build:quick` - Fast build without linting |
| 11 | +- `pnpm run watch` - Watch mode for development |
| 12 | +- `pnpm run watch:quick` - Fast watch mode without linting |
| 13 | +- `pnpm run bundle` - Production bundle |
| 14 | + |
| 15 | +### Testing & Quality |
| 16 | + |
| 17 | +- `pnpm run test` - Run unit tests with vscode-test |
| 18 | +- `pnpm run test:e2e` - End-to-end tests with Playwright |
| 19 | +- `pnpm run lint` - ESLint with TypeScript rules |
| 20 | +- `pnpm run lint:fix` - Auto-fix linting issues |
| 21 | +- `pnpm run pretty` - Format with Prettier |
| 22 | + |
| 23 | +### Specialized Commands |
| 24 | + |
| 25 | +- `pnpm run build:tests` - Build test files with esbuild |
| 26 | +- `pnpm run generate:contributions` - Generate package.json contributions from contributions.json |
| 27 | +- `pnpm run generate:commandTypes` - Generate command types from contributions |
| 28 | +- `pnpm run web` - Run extension in web environment for testing |
| 29 | + |
| 30 | +## High-Level Architecture |
| 31 | + |
| 32 | +### Core Container System |
| 33 | + |
| 34 | +- **Container** (`src/container.ts`) - Main dependency injection container, singleton pattern |
| 35 | +- All services registered in constructor and exposed as getters |
| 36 | +- Handles lifecycle, configuration changes, and service coordination |
| 37 | + |
| 38 | +### Major Services & Providers |
| 39 | + |
| 40 | +- **GitProviderService** - Core Git operations and repository management |
| 41 | +- **SubscriptionService** - GitLens Pro subscription and account management |
| 42 | +- **IntegrationService** - GitHub/GitLab/etc integrations |
| 43 | +- **AIProviderService** - AI features (commit messages, explanations) |
| 44 | +- **WebviewsController** - Manages all webview panels (Graph, Home, etc) |
| 45 | +- **AutolinksProvider** - Auto-linking issues/PRs in commit messages |
| 46 | +- **TelemetryService** - Usage analytics and error reporting |
| 47 | + |
| 48 | +### VS Code Contributions |
| 49 | + |
| 50 | +- Commands, Menus, Submenus, Keybindings, and Views are defined in `contributions.json` |
| 51 | +- Contributions are generated from `contributions.json` into `package.json` via `pnpm run generate:contributions` |
| 52 | +- Contributions can also be extracted from `package.json` into `contributions.json` via `pnpm run extract:contributions` |
| 53 | + |
| 54 | +### Webview Architecture |
| 55 | + |
| 56 | +- **Shared Components** (`src/webviews/apps/shared/`) - Common UI components using Lit |
| 57 | +- **Host-Guest Communication** - IPC between extension and webviews |
| 58 | +- **State Management** - Context providers with Lit reactive patterns |
| 59 | +- Major webviews: Home, Commit Graph, Timeline, Launchpad, Settings |
| 60 | + |
| 61 | +### Git Integration |
| 62 | + |
| 63 | +- **GitProviderService** - Abstracts Git operations across different providers |
| 64 | +- **Repository Models** - Strongly typed Git entities (Branch, Commit, Tag, etc) |
| 65 | +- **DocumentTracker** - Tracks file changes and editor state |
| 66 | +- **FileAnnotationController** - Blame, heatmap, and change annotations |
| 67 | + |
| 68 | +### Plus Features (Pro) |
| 69 | + |
| 70 | +- **Subscription gating** - Feature access control via SubscriptionService |
| 71 | +- **Cloud integrations** - GitHub/GitLab APIs for PRs, issues |
| 72 | +- **Worktrees** - Multi-branch workflow support |
| 73 | +- **AI features** - Commit generation, explanations using various providers |
| 74 | + |
| 75 | +## Coding Standards & Style Rules |
| 76 | + |
| 77 | +### TypeScript Configuration |
| 78 | + |
| 79 | +- Strict TypeScript with `strictTypeChecked` ESLint config |
| 80 | +- No `any` usage (exceptions for external APIs) |
| 81 | +- Explicit return types for public methods |
| 82 | +- Prefer `type` over `interface` for unions |
| 83 | + |
| 84 | +### Import Organization |
| 85 | + |
| 86 | +- Use path aliases: `@env/` for environment-specific code |
| 87 | +- Import order: node built-ins → external → internal → relative |
| 88 | +- No default exports (ESLint enforced) |
| 89 | +- Consistent type imports with `import type` |
| 90 | + |
| 91 | +### Naming Conventions |
| 92 | + |
| 93 | +- **Classes**: PascalCase (no `I` prefix for interfaces) |
| 94 | +- **Methods/Variables**: camelCase |
| 95 | +- **Constants**: camelCase for module-level constants |
| 96 | +- **Private members**: Leading underscore allowed |
| 97 | +- **Files**: camelCase.ts, camelCase.utils.ts for related utilities |
| 98 | +- **Folders** |
| 99 | + - Models under a `models/` sub-folder |
| 100 | + - Utilities under a `utils/` sub-folder if they can be used in both the extension host and webviews, or `utils/-webview/` sub-folder for extension host-specific utilities |
| 101 | + - Webview apps under `webviews/apps/` |
| 102 | + |
| 103 | +### Code Structure |
| 104 | + |
| 105 | +- **Single responsibility** - Each service has focused purpose |
| 106 | +- **Dependency injection** - Services injected via Container |
| 107 | +- **Event-driven** - EventEmitter pattern for service communication |
| 108 | +- **Disposable pattern** - Proper cleanup with VS Code Disposable interface |
| 109 | + |
| 110 | +### Error Handling |
| 111 | + |
| 112 | +- Use custom error types extending Error |
| 113 | +- Log errors with context using Logger.error() |
| 114 | +- Graceful degradation for network/API failures |
| 115 | +- Validate external data with schema validators |
| 116 | + |
| 117 | +### Webview Specific |
| 118 | + |
| 119 | +- **Lit Elements** - Use for reactive UI components |
| 120 | +- **Context providers** - For sharing state across components |
| 121 | +- **Signal patterns** - For reactive state management |
| 122 | +- **CSS custom properties** - For theming support |
| 123 | + |
| 124 | +### Environment Abstractions |
| 125 | + |
| 126 | +- **Platform detection** - Use `@env/platform` abstractions |
| 127 | +- **Node vs Browser** - Environment-specific implementations in `src/env/` |
| 128 | +- **WebWorker support** - Browser extension compatibility |
| 129 | + |
| 130 | +## Repository Guidelines |
| 131 | + |
| 132 | +### Commit Messages |
| 133 | + |
| 134 | +- Use a future-oriented manner, third-person singular present tense (e.g., 'Fixes', 'Updates', 'Improves', 'Adds', 'Removes') |
| 135 | +- Reference issues with `#123` syntax for auto-linking |
| 136 | +- Keep first line under 72 characters |
| 137 | + |
| 138 | +### Branch Workflow |
| 139 | + |
| 140 | +- Feature branches from `main` |
| 141 | +- Prefix with feature type: `feature/`, `bug/`, `debt/` |
| 142 | +- Use descriptive names: `feature/search-natural-language` |
| 143 | + |
| 144 | +### Code Reviews |
| 145 | + |
| 146 | +- Check TypeScript compilation and tests pass |
| 147 | +- Verify no new ESLint violations |
| 148 | +- Test webview changes in both themes |
| 149 | +- Validate Plus features with subscription states |
| 150 | + |
| 151 | +## Key Extension Points |
| 152 | + |
| 153 | +### Adding New Commands |
| 154 | + |
| 155 | +1. Define in `src/commands/` directory |
| 156 | +2. Register in `src/commands.ts` |
| 157 | +3. Add to `contributions.json` for package.json generation |
| 158 | +4. Update command types with `pnpm run generate:commandTypes` |
| 159 | + |
| 160 | +### New Webviews |
| 161 | + |
| 162 | +1. Create provider in `src/webviews/` |
| 163 | +2. Add Lit app in `src/webviews/apps/` |
| 164 | +3. Register in WebviewsController |
| 165 | +4. Add protocol definitions for IPC |
| 166 | + |
| 167 | +### Git Provider Extensions |
| 168 | + |
| 169 | +- Implement GitProvider interface |
| 170 | +- Register with GitProviderService |
| 171 | +- Handle provider-specific authentication |
| 172 | + |
| 173 | +### AI Provider Integration |
| 174 | + |
| 175 | +- Implement AIProvider interface |
| 176 | +- Add to AIProviderService registry |
| 177 | +- Handle authentication and rate limiting |
| 178 | + |
| 179 | +## Development Environment |
| 180 | + |
| 181 | +### Prerequisites |
| 182 | + |
| 183 | +- **Node.js** ≥ 22.12.0 |
| 184 | +- **pnpm** ≥ 10.x (via corepack) |
| 185 | +- **Git** ≥ 2.7.2 |
| 186 | + |
| 187 | +### VS Code Tasks |
| 188 | + |
| 189 | +- **Build** - `Ctrl+Shift+P` → "Tasks: Run Task" → "watch" |
| 190 | +- **Test** - Use VS Code's built-in test runner |
| 191 | +- **Debug** - F5 to launch Extension Development Host |
| 192 | + |
| 193 | +### Multi-target Support |
| 194 | + |
| 195 | +- **Node.js** - Traditional VS Code extension |
| 196 | +- **Web Worker** - Browser/web VS Code compatibility |
| 197 | +- Shared code with environment abstractions |
| 198 | + |
| 199 | +This architecture enables GitLens to provide powerful Git tooling while maintaining clean separation of concerns and extensibility for new features. |
0 commit comments