Git Blame Lens - VS Code Extension

A powerful VS Code extension that shows Git blame annotations and repository history, similar to GitLens.

Features

1. Inline Blame Annotations

Shows who made changes to each line directly in the editor with:

• Author name
• Commit date (relative time)
• Commit hash
• Hover for full commit details

2. Repository History View

Browse your repository's commit history in the SCM sidebar:

• View all commits with author, date, and message
• Click to see commit details
• Organized chronologically

3. File History

View the complete history of the current file:

• All commits that modified the file
• Quick navigation to specific commits
• Diff view for each commit

4. Line History

Track changes to specific lines:

• See all commits that touched a particular line
• Understand the evolution of your code

Installation & Setup

Prerequisites

• VS Code 1.85.0 or higher
• Node.js 20.x or higher
• Git installed and configured

Building the Extension

1. Clone or create the project:

cd git-lens-extension

2. Install dependencies:

npm install

3. Compile TypeScript:

npm run compile

4. Run in Development Mode:
   • Press F5 in VS Code to open Extension Development Host
   • Or use the "Run Extension" debug configuration

Installing Locally

To install the extension in your VS Code:

1. Package the extension:

npm install -g @vscode/vsce
vsce package

2. Install the .vsix file:

code --install-extension git-blame-lens-0.1.0.vsix

Or use VS Code UI:

• Open Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
• Click "..." menu → "Install from VSIX..."
• Select the generated .vsix file

Usage

Commands

All commands are available via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

• Git Blame: Toggle Blame Annotations - Show/hide inline blame annotations
• Git Blame: Show File History - View history of current file
• Git Blame: Show Repository History - Open repository history view
• Git Blame: Show Line History - View history of current line

Keyboard Shortcuts (Optional)

Add to your keybindings.json:

{
  "key": "ctrl+shift+g b",
  "command": "gitBlameLens.toggleBlame"
},
{
  "key": "ctrl+shift+g h",
  "command": "gitBlameLens.showFileHistory"
}

Configuration

Open Settings (Ctrl+, / Cmd+,) and search for "Git Blame Lens":

{
  // Enable/disable the extension
  "gitBlameLens.enabled": true,
  
  // Show blame annotations when opening files
  "gitBlameLens.showBlameOnStartup": true,
  
  // Date format for annotations
  "gitBlameLens.dateFormat": "YYYY-MM-DD",
  
  // Color for blame annotations (hex with alpha)
  "gitBlameLens.annotationColor": "#99999959"
}

How It Works

Blame Annotations

The extension uses git blame --line-porcelain to get detailed information about each line:

• Who authored it
• When it was committed
• The commit message
• The commit hash

Annotations appear at the end of each line showing:

Author Name, 2 hours ago • abc1234

Hover over any annotation to see:

• Full author name and email
• Complete commit message
• Exact date and time
• Full commit hash
• Link to view the commit

Repository History

The history view in the SCM sidebar shows:

• Last 100 commits (configurable)
• Commit message, author, and relative time
• Click any commit to view its diff

Development

Project Structure

git-lens-extension/
├── src/
│   ├── extension.ts           # Main entry point
│   ├── models/
│   │   └── types.ts           # Type definitions
│   ├── providers/
│   │   ├── blameProvider.ts   # Blame annotations
│   │   └── historyProvider.ts # History tree view
│   └── services/
│       └── gitService.ts      # Git command execution
├── package.json               # Extension manifest
└── tsconfig.json             # TypeScript config

Key Technologies

• TypeScript - Type-safe development
• VS Code Extension API - Editor integration
• Git CLI - Repository interaction
• Decorators API - Inline annotations

Adding Features

To add new features:

1. Add command to package.json:

{
  "command": "gitBlameLens.myCommand",
  "title": "Git Blame: My Command"
}

2. Register command in extension.ts:

context.subscriptions.push(
  vscode.commands.registerCommand('gitBlameLens.myCommand', async () => {
    // Implementation
  })
);

3. Implement in service (gitService.ts) if needed

Testing

Run the extension in debug mode:

1. Open the project in VS Code
2. Press F5 to launch Extension Development Host
3. Open a Git repository in the new window
4. Test the features

Debugging

• Set breakpoints in TypeScript files
• Use Debug Console for logging
• Check Output panel → "Extension Host" for errors

Roadmap

Phase 1 (Current)

• ✅ Inline blame annotations
• ✅ Repository history view
• ✅ File history
• ✅ Line history

Phase 2 (Planned)

• Commit details panel
• Branch visualization
• Blame heatmap (visual indicators of code age)
• Compare commits
• Search commits

Phase 3 (Future)

• Interactive rebase UI
• Code authorship analytics
• Integration with GitHub/GitLab
• Team contribution graphs

Troubleshooting

Blame annotations not showing

• Ensure you're in a Git repository
• Check that Git is installed: git --version
• Verify the file is tracked by Git
• Check extension is enabled in settings

Performance issues

• Reduce history limit in settings
• Disable blame on large files
• Use git blame cache (future feature)

Commands not appearing

• Reload VS Code window
• Check Command Palette for errors
• Verify extension is activated

Contributing

Contributions welcome! Areas to improve:

• Performance optimization
• Additional Git operations
• UI/UX enhancements
• Configuration options
• Testing coverage

License

MIT

Credits

Inspired by GitLens by Eric Amodio.

---

Enjoy coding with better Git insights! 🚀