gitrim 0.1.0

CLI tool to detect large files in Git history and working directory with pre-commit hook support.

Gitrim

Keep your git repositories clean and lean!

Gitrim is a powerful, user-friendly CLI tool to help you detect, block, and remove large files from your git repositories and working directories. It also helps you prevent accidental commits of oversized files with a pre-commit hook.

---

🚀 Features

• 🔍 Scan git history for large files
• 📂 Scan working directory for large files
• 🗑️ Remove large files from the working directory (with dry-run and confirmation)
• 🛡️ Generate a pre-commit hook to block large files from being committed
• 📏 Flexible size threshold (KB, MB, GB)
• 📊 Summary statistics after each operation
• 🤝 User-friendly CLI with helpful usage info
• ⚠️ Clear error handling and confirmation prompts

---

🛠️ Installation

1. Clone this repository:

   git clone https://github.com/yadavkapil23/Gitrim.git
   cd Gitrim
   

2. (Recommended) Create and activate a virtual environment:

   python -m venv gitrim-env
   # On Windows:
   gitrim-env\Scripts\activate
   # On macOS/Linux:
   source gitrim-env/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. (Optional) Install in editable/development mode:

   pip install -e .
   

5. Verify installation:

   gitrim --help
   

---

⚡ Usage

Run gitrim to see all commands and examples:

$ gitrim

1. 🔍 Scan git history for large files

$ gitrim large-files --threshold 5 --unit MB

• Scans the entire git history for files larger than 5 MB.

2. 📂 Scan working directory for large files

$ gitrim scan-working-dir --threshold 500 --unit KB

• Scans only the current working directory (not git history) for files larger than 500 KB.

3. 🗑️ Remove large files from working directory

• Dry run (no deletion):

  $ gitrim remove-large-files --threshold 2 --unit MB --dry-run
  

• Actually delete (with confirmation):

  $ gitrim remove-large-files --threshold 2 --unit MB
  

• Actually delete (no confirmation):

  $ gitrim remove-large-files --threshold 2 --unit MB --yes
  

4. 🛡️ Generate a pre-commit hook

$ gitrim generate-pre-commit-hook --threshold 1 --unit MB

• Creates a .git/hooks/pre-commit script that blocks commits containing files above the threshold.

5. Get help for any command

$ gitrim --help
# or
$ gitrim <command> --help

---

📦 Components

• gitrim/cli.py

  • The main CLI entry point. Defines all commands and options using Click.
  • Handles user input, help messages, and command dispatch.

• gitrim/cleaner.py

  • Contains all core logic for scanning, reporting, removing large files, and generating pre-commit hooks.
  • Handles both git history and working directory operations.
  • Provides summary statistics and user feedback.

• requirements.txt

  • Lists all Python dependencies: click, rich, GitPython.

• README.md

  • This file! Explains installation, usage, and features.

• pyproject.toml

  • Used for editable installs and packaging.

---

📝 Example Workflow

1. Scan your repo for large files:

   $ gitrim large-files --threshold 10 --unit MB
   

2. Scan your working directory:

   $ gitrim scan-working-dir --threshold 500 --unit KB
   

3. Remove large files (with confirmation):

   $ gitrim remove-large-files --threshold 5 --unit MB
   

4. Block large files from being committed:

   $ gitrim generate-pre-commit-hook --threshold 2 --unit MB
   

---

📄 License

MIT License. See LICENSE for details.