gitpr-cli 0.0.24

Automação de PRs, Commits e Code Review com IA (Gemini e DeepSeek)

GitPR CLI 🚀

GitPR CLI is a command-line automation tool that uses Google Gemini and DeepSeek artificial intelligence to analyze your code changes (git diff) or entire files. The tool automatically generates commit messages in the Conventional Commits standard, detailed Pull Request descriptions, and deep Code Reviews aimed at reducing technical debt.

🛠️ Technologies and Libraries Used

This project was developed in Python and uses the following main libraries:

• Click: To create a robust and user-friendly command-line interface (CLI).
• Google GenAI: Official SDK for direct integration with the Gemini API.
• OpenAI: Library used due to its full compatibility with the powerful DeepSeek API.
• Python-dotenv: For secure environment variable management.
• Pytest: For running unit tests in a simple, colorful, and readable way in the console.
• Cryptography: To ensure your GEMINI_API_KEY is stored encrypted and securely on disk.
• PyYAML: Used to read and process the custom static analysis rules from the .gitpr.linter.yml file.
• Textual: Powerful library for creating Terminal Graphical Interfaces (TUI), used in the interactive issue generation and editing panel.
• Requests: Elegant and robust library for HTTP requests, used to communicate with the GitHub REST API.

---

📦 How to Compile the Executable Locally

If you want to generate your own binary from the source code, we use PyInstaller. Make sure you are in the project root directory with the virtual environment configured.

1. Install development dependencies (if you haven't already):

   pipenv install --dev
   

2. Run the build command pointing to our entry point (run.py):

   pipenv run pyinstaller --noconfirm --onefile --icon=icon.ico --name gitpr run.py
   

Technical note: The --onefile flag ensures all Python, libraries, and dependencies are compressed into a single binary, while --paths src helps the compiler find our core.py and config.py files. 🛠️

After running this command, PyInstaller will create some folders (build and dist). Your final ready-to-use file will be inside the dist/ folder named gitpr (or gitpr.exe on Windows).

---

🧪 Running Tests

To ensure the Git capture logic and AI integration are working correctly, we use unit tests.

1. Install test dependencies (if you haven't already):

   pipenv install --dev pytest
   

2. Run the tests with the command:

   pipenv run pytest -v
   

Pytest will automatically detect files inside the tests/ folder and display a detailed execution report.

---

⚙️ Installation and Configuration

Using the Executable (Recommended)

1. Download the gitpr executable file from the "Releases" tab on GitHub.
2. Move the executable to a folder that is in your PATH (e.g.: /usr/local/bin on Linux/Mac or your user folder on Windows).
3. On the first run, the wizard will guide you:

   $ gitpr
   

🚀 Intelligent PR Automation with AI

🔧 First run detected! Let's configure GitPR CLI.

🔑 Enter your GEMINI_API_KEY:

📄 Default output filename pattern [{branch}_{datetime}_PR_DESC.md]:

Note: Your configuration will be securely saved in the ~/.gitpr/.env file.

🔒 Security Note: GitPR CLI uses symmetric encryption (Fernet). Your API key is stored as a hash in the .env file, and the master key for decryption is automatically generated in ~/.gitpr/secret.key. Never share your secret.key file.

From Source Code

1. Clone the repository: git clone https://github.com/natanfiuza/gitpr.git

2. Enter the folder: cd gitpr

3. Set up the environment:

pipenv install google-genai openai python-dotenv click cryptography

4. Run: pipenv run python src/main.py

💻 How to Use

GitPR has a powerful default behavior and several advanced options to assist you in your day-to-day as a developer.

Default Behavior (Pull Request)

Simply run the bare command in your terminal:

gitpr

The tool will sync with the remote (git fetch), compare your changes with the remote main branch (e.g.: origin/main), and generate a Markdown file (e.g.: feature-login_20260421110134_PR_DESC.md) at the root of your project with the complete suggestion for your Pull Request.

Advanced Options and Commands

You can pass the following flags for specific actions:

• -c or --commit: Runs a local git diff and displays only the suggested commit message.
• -r or --review: Performs a detailed Code Review of local changes.
• -f or --fullreview: Performs a Full Code Review analyzing all changes since the remote branch.
• -i <file> or --input <file>: Full File Audit. Must be used together with -r or -f; it ignores git history and does a Code Review of the entire file. Excellent for acting as a consultant on legacy code refactoring.
• --provider <gemini|deepseek>: Forces the use of a specific AI only for this execution, ignoring your default saved in .env.
• -l or --linter: Runs only the local static linter (no AI calls). Ideal for use in CI/CD pipelines to block non-compliant code.
• -ih or --installhooks: Automatically installs local Git Hooks (pre-commit and prepare-commit-msg) in your repository.
• -s or --skill: Creates the AI context template files (.gitpr.commit.md, .gitpr.pr.md, .gitpr.review.md, .gitpr.filereview.md, .gitpr.issue.md, .gitpr.blame.md) and the Linter (.gitpr.linter.yml) at the project root.
• -is or --issue: Automatically generates a draft of a standardized Issue and opens an interactive interface (TUI) for editing or direct submission via REST API. This feature has 3 context engines depending on the command combination:
  • New Code Issue (gitpr -is): Reads the current git diff. Why use: Ideal for quickly documenting the task you just finished programming, before committing.
  • Epic/Release Issue (gitpr -is -ht): Reads the full history of the current branch (Git Log + PR Cache). Why use: Ideal for generating consolidated documentation of an entire release or a large feature that took several days/commits to complete.
  • Archaeological/Technical Debt Issue (gitpr -is -b file:lines): Reads the timeline of a specific business rule. Why use: Ideal for documenting technical debt, explaining how a legacy code block evolved and why it needs to be refactored.
• -h or --help: Shows the general help with all options. Use together with another flag for contextual help (e.g.: gitpr -h --issue, gitpr -h --linter) with a direct link to the detailed documentation of each feature.
• -u or --update: Checks and installs the latest version of GitPR (Auto-Updater).

⚙️ Technical Note (--hook): GitPR has a hidden flag --hook <file> that is triggered exclusively by the Git Hooks system in the background. It allows the AI to inject the suggested message directly into Git's temporary file, without cluttering your terminal.

🛡️ Local Linter (Static Analysis)

GitPR CLI allows you to define strict rules that will be validated instantly during --review or --fullreview, without depending on AI. This is ideal for preventing common errors (like console.log or test IPs) from reaching the repository.

How to configure .gitpr.linter.yml:

When running gitpr --skill, a template will be generated. You can configure rules using Regular Expressions (Regex):

rules:
  - name: "check-localhost"
    extensions: ["js", "php"] # Extensions to be validated
    regex: 'http(s)?://(localhost|127\.0\.0\.1)' # What to look for
    message: "🚨 Localhost usage detected in file {file_name}"
    ignore_comments: true # Ignores if the line is commented
    ignore_paths: # Folders or files ignored (accepts *)
      - "vendor/*"
      - "node_modules/*"

The Linter analyzes only the added lines in your git diff, ensuring a focused and extremely fast execution. If there are violations, they will appear highlighted at the top of your review file.

🧠 Multi-Model Architecture (AI-Agnostic)

GitPR is not tied to a single Artificial Intelligence. During initial setup, the user can choose their default engine. We currently support:

• Google Gemini (Default: gemini-2.5-flash)
• DeepSeek (Default: deepseek-chat)

You can dynamically switch models by configuring the GEMINI_API_MODEL or DEEPSEEK_API_MODEL variables in your ~/.gitpr/.env file, or switch in real-time using the --provider flag.

🎯 Customizable "Skills" System (Prompt Engineering)

Instead of hiding AI instructions in the source code, GitPR uses local Markdown files that act as System Instructions. When running gitpr -s, the following files are generated at the root of your project to customize the AI's "persona" according to your company's business rules:

• .gitpr.commit.md: Rules for generating short commit messages.
• .gitpr.pr.md: Required topic structure for the Pull Request description.
• .gitpr.review.md: Defines the architectural focus (e.g.: SOLID, Clean Code) for diff analysis.
• .gitpr.filereview.md: Defines strict cohesion and coupling rules for full file auditing (used with --input).
• .gitpr.issue.md: Defines the structure and level of detail required for generating standardized Issues (used with --issue).
• .gitpr.blame.md: Defines the focus of archaeological analysis for legacy code tracing (used with --blame).

🌐 Internationalization (i18n)

GitPR automatically detects your system language and displays messages in your native language. The i18n system is inspired by Laravel's __() helper:

• Auto-detection: On first run, GitPR detects your OS language and saves it to ~/.gitpr/.env (GITPR_LANG).
• Translation files: Language packs are downloaded automatically from the official repository to ~/.gitpr/langs/.
• English fallback: If a translation is missing, the English text is displayed directly.
• Developer API: Use from src.i18n import __ and wrap all user-facing strings with __("Your text here").
• Placeholders: Supports named parameters — __("Downloading {file}...", file="template.md").

To force a specific language, set GITPR_LANG=pt_br or GITPR_LANG=en in ~/.gitpr/.env.

📖 Full developer guide: docs/i18n_explanation.md — architecture, usage patterns, circular import precautions, and how to add new languages.

📚 Technical Documentation and Advanced Guides

To keep this README concise, we detail the most advanced DevOps and Continuous Integration focused implementations in separate documents.

If you want to implement GitPR as an automated quality barrier in your team, check out the guides below:

• Local Git Hooks (Shift-Left): How to use gitpr --installhooks to create guardrails on the developer's machine and use AI to automatically write commit messages.
• Customizable Static Linter: How to create validation rules in .gitpr.linter.yml for CI/CD and pre-commit hooks.
• Issue Generation and TUI Interface: How to use the terminal graphical interface (TUI) and the 3 context engines to manage structured Issues.
• AI Code Review: Guide to review modes (--review, --fullreview) and file auditing (--input).
• AI Commit Messages: How to generate messages in the Conventional Commits standard and integrate with Git Hooks.
• Code Archaeologist (Git Blame): How to trace the origin of business rules with git blame and AI.
• Skills and Templates System: How to customize AI behavior with .gitpr.*.md files.
• Auto-Updater: How GitPR's automatic update (hot-swap) works.
• AI Providers: Configuration and selection between Google Gemini and DeepSeek.
• Pull Request (Default Mode): Complete flow for generating PR descriptions without flags.
• CI/CD Integration (GitHub Actions): How to run GitPR in the pipeline to block "Merge" of PRs with violations.
• GitHub Token (PAT) Integration and Security: Understand how GitPR creates issues directly in the repository with authentication.

⚡ Local Cache System (Quota Savings)

GitPR has an intelligent MD5-based cache engine. Whenever you run a command (--review, --commit, etc.), the tool generates an exact hash of your current code (diff) and instructions. If you run the same command again without changing the code, GitPR intercepts the request and returns the result instantly (in milliseconds) from the ~/.gitpr/cache/prompts/ folder, saving you time and your Gemini API quotas!

🔄 Auto-Updater (Over-The-Air Update)

Never worry about manually downloading new versions again. GitPR has a Connection Guardian and a built-in updater:

• It checks network availability before starting so it doesn't block your offline workflow.
• On each execution, it silently checks if there is a new official release on the GitHub API.
• You can force the check and installation by running gitpr --update or gitpr -u.
• The tool uses the Hot-Swap technique, downloading the new .exe and transparently replacing the old version.

Publishing to PyPI

pipenv run python -m build
pipenv run twine upload dist/*

🤝 How to Contribute

Contributions are very welcome! To contribute:

1. Fork the project.
2. Create a branch for your feature (git checkout -b feature/NewFeature).
3. Commit your changes (git commit -m 'feat: add new feature'). Tip: Use GitPR itself to generate this message! 😄
4. Push to the branch (git push origin feature/NewFeature).
5. Open a Pull Request.

✨ Acknowledgments and Authorship

Project conceived and developed by:

Natan Fiuza - [e-mail]

📄 License

This project is licensed under the GNU Lesser General Public License v2.1 (LGPL-2.1). See the LICENSE file for more details.