📋 Table of Contents
What is GitIngest?
GitIngest is a code editor extension that analyzes your entire codebase—Git repos or local folders—so you can explore structure, detect patterns, and export insights without leaving your editor.
🌟 Why Choose GitIngest?
|
🔧 Zero Setup Required
- No CLI installation needed
- Everything runs within your editor
- Works offline with 100% local execution
|
🌍 Universal Compatibility
- Supports any codebase (Git or non-Git)
- Cross-platform (Windows, macOS, Linux)
- Smart filtering of unnecessary files
|
Key Features
🎨 Modern Interface
- Beautiful three-panel webview layout
- Interactive directory tree visualization
- Real-time progress indicators
- Responsive design for all screen sizes
- One-click copy functionality
|
🔍 Smart Analysis
- Comprehensive codebase scanning
- Intelligent file filtering
- Summary insights and metrics
- Searchable and exportable results
- Custom folder selection
|
⚡ Seamless Integration
- Right-click menus in Explorer and Source Control
- Command palette integration
- No external dependencies
- Instant results in webview
|
🛠 Flexible Workflow
- Analyze entire repositories
- Target specific folders
- Include / exclude patterns and size limits
- Staged files keep their original paths
- Optional cleanup after analysis
|
Quick Start
Prerequisites
Before getting started, ensure you have:
- VS Code 1.54.0 or higher
- Python 3.x installed and added to your system PATH
💡 Quick Check: Open a terminal and run python --version or python3 --version to verify installation
Installation & First Analysis
📦 Install the Extension
- Open Editor Extensions (Ctrl/Cmd + Shift + X)
- Search for "GitIngest"
- Click Install
🎯 Analyze Your First Repository
- Open any project folder in your editor
- Right-click a folder in Explorer, or changed files/folders in Source Control
- Select "GitIngest: Analyze This Folder"
- View results in the webview panel!
Usage Guide
Method 1: Quick Analysis (Recommended)
🖱️ Right-Click Analysis
Perfect for immediate analysis of any folder
- Right-click a folder in Explorer, or changed files/folders in Source Control
- Choose "GitIngest: Analyze This Folder" — Explorer digests the full folder; Source Control digests only the selected changes
- View results in the automatically opened webview panel
Cross-editor note: VS Code and Cursor hand the extension the exact file/folder you clicked in Source Control, so analysis is one click. Some editors (e.g. Kiro) don't resolve the clicked item for third-party extensions — there, GitIngest shows a quick folder picker built from your actual changes so you can still scope to one folder. See docs/KIRO-SCM-BUG.md for details.
Method 2: Selective Analysis (Advanced)
🎯 Cherry-Pick Your Files
Ideal for large codebases where you only need specific parts analyzed
- Right-click files/folders in Explorer or Source Control (Ctrl/Cmd for multi-select in Explorer), or right-click a Source Control group such as Changes and choose Add to Ingest (or Analyze This Folder on Changes to digest those changes directly)
- Select "GitIngest: Add To Ingest" for each item (groups stage every change in that group)
- Once you've selected all desired items, run "GitIngest: Analyze This Folder" on the ingest folder (or analyze another folder as needed)
- Optionally enable auto-cleanup in settings
Staged items keep their location: src/utils/helpers/example.ts is staged as
gitingest-ingest/src/utils/helpers/example.ts, so the digest still shows where each file lives.
Adding a folder you have already staged files from fills the same mirrored folder rather than
creating a second one. Files that would overwrite an existing staged copy get a (1) /
(2) suffix instead — so staging a nested file and then its parent folder can leave both
example.ts and example (1).ts when the folder copy would collide. Set
gitingest.preserveStructureOnAdd to false to stage everything flatly by name instead.
Method 3: Command Palette
⌨️ Keyboard-First Approach
- Press
Ctrl/Cmd + Shift + P to open Command Palette
- Type and select "GitIngest: Analyze Repository"
- Follow the prompts and review your analysis
Understanding Your Analysis
Your analysis results are presented in three comprehensive panels:
📋 Summary Panel
📈 Repository Overview
├── 📁 Files Analyzed: 156
├── 📊 Estimated Tokens: 12,450
├── 🗂️ Directory Structure
└── 📝 File Content Analysis
Export Options Available:
🌳 Directory Structure
Interactive tree view with smart filtering:
- ✅ Source code files included
- ❌ Build artifacts excluded
- ❌ Node_modules filtered out
- ❌ IDE-specific files hidden
Click any entry in the tree to filter it: it is struck through when excluded, highlighted when
included, and clicking again undoes it. Which list you are editing follows the Exclude / Include
selector above, and folders are added as <folder>/**. An entry is never in both lists. The digest
only re-runs when you press Re-Ingest, so you can mark several entries in one pass.
🎚️ Filters & Re-Ingest
Above the results, the same controls gitingest.com gives you:
- an Exclude / Include selector and one pattern field (
*.md, src/)
- an Include files under slider for the size limit
Press Re-Ingest to re-run with the new filters, or Reset to Settings to go back to your
configured defaults. The row edits one list at a time: switching Exclude / Include keeps the
other list in the background, so configured exclusions stay available while you narrow with an
include pattern. When both lists have values after a run, the field opens on Exclude so those
patterns stay visible; switch to Include to see or edit that list. GitIngest: Re-Ingest Last
Folder (Command Palette) reuses the last filters applied from the panel, not a fresh read of
settings.
📄 File Content Analysis
Detailed breakdown including:
- Code snippets and key functions
- Documentation and README files
- Configuration files
- Dependencies and imports
Available Export Formats:
- 📋 Copy to Clipboard - Quick sharing
- 💾 Save as Text - Local backup
- 📝 Open in Editor - Review the digest in an unsaved tab, no file written
Configuration & Settings
Automatic Management
GitIngest handles these automatically:
- ✅ Python environment detection
- ✅ GitIngest package verification
- ✅ Platform-specific command execution
- ✅ Intelligent process management
Customizable Options
Access via File > Preferences > Settings > Extensions > GitIngest:
| Setting |
Default |
What it does |
gitingest.ingestFolderName |
gitingest-ingest |
Folder used to stage files when using Add to Ingest. |
gitingest.preserveStructureOnAdd |
true |
Keep the workspace-relative path of staged files and folders. |
gitingest.deleteAfterIngest |
false |
Delete the Add to Ingest staging folder after you successfully analyze that staging folder (not after analyzing other folders). |
gitingest.fileExclusions |
**/node_modules, **/.git |
Glob patterns to exclude, in addition to .gitignore and .gitingestignore. |
gitingest.includePatterns |
(empty) |
Glob patterns to include; when empty, everything that is not excluded is included. |
gitingest.maxFileSize |
10485760 (10 MB) |
Maximum size in bytes of a single file in the digest. |
These pattern and size settings seed the filter bar in the results panel, which can override them
for a single run. Panel overrides are what Re-Ingest Last Folder replays.
.gitingestignore
You can add a .gitingestignore file in the root of the folder you are analyzing. It uses the same format as .gitignore. Files and folders listed there are excluded from ingestion but remain in version control, so you don't need to add them to .gitignore just to keep them out of the digest.
The engine respects both .gitignore and .gitingestignore by default. A recent version of the gitingest Python package (e.g. 0.3.x) is required for .gitingestignore support.
Troubleshooting
Common Issues & Quick Fixes
🐍 Python Not Found Error
Problem: Extension can't locate Python installation
Quick Solutions:
- Install Python 3.x from python.org
- Ensure "Add Python to PATH" is checked during installation
- Restart your editor after installation
- Test with
python --version in terminal
Platform-Specific Help:
- Windows: Use "Add Python to PATH" option during installation
- macOS: Install via Homebrew:
brew install python3
- Linux: Install via package manager:
sudo apt install python3
⚠️ Analysis Failing or Hanging
Problem: Analysis starts but doesn't complete
Solutions:
- Check file permissions - Ensure your editor can read project files
- Close other Python processes - Free up system resources
- Restart your editor - Clear any stuck processes
- Try a smaller folder first - Test with a simple project
For Large Repositories:
- Use selective analysis instead of full repository scan
- Exclude large directories (node_modules, .git, build folders)
- Consider analyzing in smaller chunks
🔧 Extension Not Loading
Problem: GitIngest commands not appearing in Editor
Solutions:
- Reload your editor - Use
Ctrl/Cmd + Shift + P > "Reload Window"
- Check extension status - Ensure it's enabled in your Extensions panel
- Update your editor - Ensure you're using a compatible version
- Reinstall extension - Remove and reinstall from marketplace
Need More Help?
- 📝 Check the Developer Console:
Help > Toggle Developer Tools
- 🐛 Report bugs on GitHub Issues
- 💬 Join discussions in our GitHub repository
Privacy & Security
Your privacy and security are our top priorities:
🔒 100% Local Execution
- All analysis happens on your machine
- No code sent to external servers
- No internet connection required
🔐 Zero Data Collection
- We don't collect or store any of your code
- No telemetry or usage tracking
- Your intellectual property stays private
🛡️ Safe Operation
- Read-only analysis of your files
- No modifications to your codebase
- Optional cleanup features with user consent
Contributing
GitIngest is open source and we welcome contributions.
- 🌟 Star the repository – Help others discover GitIngest
- 🐛 Report bugs – Open an issue
- 💡 Suggest features – Share ideas via GitHub Discussions or issues
- 🔧 Contribute code – See CONTRIBUTING.md for development setup, code style, and how to submit pull requests
📜 License
This project is licensed under the MIT License. See the LICENSE file for complete details.
🙌 Acknowledgments
💙 GitIngest – Core engine.
💙 VS Code API – Enabling smooth integration.
Made with ❤️ for developers worldwide.
⭐ If this extension helped you, please consider giving it a star on the GitHub and marketplace!
