gitpr-cli 0.0.26__tar.gz → 0.0.27__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {gitpr_cli-0.0.26/gitpr_cli.egg-info → gitpr_cli-0.0.27}/PKG-INFO +14 -1
- gitpr_cli-0.0.26/PKG-INFO → gitpr_cli-0.0.27/README.md +265 -270
- gitpr_cli-0.0.26/README.md → gitpr_cli-0.0.27/gitpr_cli.egg-info/PKG-INFO +283 -252
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/gitpr_cli.egg-info/SOURCES.txt +4 -1
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/pyproject.toml +1 -1
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/ai_providers.py +59 -1
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/blame_engine.py +2 -2
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/core.py +148 -18
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/issue_engine.py +1 -1
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/main.py +7 -1
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/spinner.py +22 -6
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/updater.py +2 -2
- gitpr_cli-0.0.27/tests/test_pre_save.py +66 -0
- gitpr_cli-0.0.27/tests/test_smart_excludes.py +71 -0
- gitpr_cli-0.0.27/tests/test_thinking_words.py +52 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/LICENSE +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/gitpr_cli.egg-info/dependency_links.txt +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/gitpr_cli.egg-info/entry_points.txt +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/gitpr_cli.egg-info/requires.txt +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/gitpr_cli.egg-info/top_level.txt +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/setup.cfg +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/__init__.py +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/cache.py +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/chat_memory.py +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/config.py +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/i18n.py +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/linter_engine.py +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/security.py +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/tui_issue.py +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/ui/__init__.py +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/ui/chat_app.py +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/ui/help_screen.py +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/src/ui/issue_app.py +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/tests/test_chat_backend.py +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/tests/test_core.py +0 -0
- {gitpr_cli-0.0.26 → gitpr_cli-0.0.27}/tests/test_skill_command.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: gitpr-cli
|
|
3
|
-
Version: 0.0.
|
|
3
|
+
Version: 0.0.27
|
|
4
4
|
Summary: Automação de PRs, Commits e Code Review com IA (Gemini e DeepSeek)
|
|
5
5
|
Author-email: Natan Fiuza <contato@natanfiuza.dev.br>
|
|
6
6
|
Requires-Python: >=3.10
|
|
@@ -16,8 +16,13 @@ Requires-Dist: textual
|
|
|
16
16
|
Requires-Dist: requests
|
|
17
17
|
Dynamic: license-file
|
|
18
18
|
|
|
19
|
+
|
|
19
20
|
# **GitPR CLI 🚀**
|
|
20
21
|
|
|
22
|
+
<p align="center">
|
|
23
|
+
<img src="docs/logo.png" alt="GitPR Logo" width="200">
|
|
24
|
+
</p>
|
|
25
|
+
|
|
21
26
|
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.
|
|
22
27
|
|
|
23
28
|
## **🛠️ Technologies and Libraries Used**
|
|
@@ -140,6 +145,14 @@ You can pass the following *flags* for specific actions:
|
|
|
140
145
|
* `-u` or `--update`: Checks and installs the latest version of GitPR (Auto-Updater).
|
|
141
146
|
|
|
142
147
|
> **⚙️ 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.
|
|
148
|
+
>
|
|
149
|
+
> **⚙️ Technical Note (--pre-save):** GitPR has a hidden debug flag `--pre-save` that can be combined with any AI command (e.g.: `gitpr -c --pre-save`). Before each AI call, it saves the full payload that will be sent to the model (system instruction + prompt + character counters) to a `_{action}-{datetime}.json` file in the current folder, and then proceeds normally. Useful for inspecting very large prompts. Note: when the response comes from the local cache, no call is made and no file is generated.
|
|
150
|
+
|
|
151
|
+
### 📦 Huge Diffs (Map-Reduce)
|
|
152
|
+
|
|
153
|
+
When your diff is too large for a single AI call (over ~90k estimated tokens), GitPR automatically splits it into batches by file, asks the AI for a technical summary of each part (Map), and unifies everything into the final commit message, review, or PR description (Reduce). No flags needed — it activates on demand and shows the progress in the console.
|
|
154
|
+
|
|
155
|
+
📚 Full documentation: [docs/map-reduce-diff.md](docs/map-reduce-diff.md)
|
|
143
156
|
|
|
144
157
|
## 🛡️ Local Linter (Static Analysis)
|
|
145
158
|
|
|
@@ -1,270 +1,265 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
```bash
|
|
71
|
-
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
*
|
|
126
|
-
* `-
|
|
127
|
-
* `-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
* `.gitpr.
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
* [
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
* [**
|
|
215
|
-
* [**
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
* [**
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
* [**
|
|
224
|
-
* [**
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
##
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
**Natan Fiuza** - [contato@natanfiuza.dev.br](mailto:contato@natanfiuza.dev.br)
|
|
267
|
-
|
|
268
|
-
## **📄 License**
|
|
269
|
-
|
|
270
|
-
This project is licensed under the **GNU Lesser General Public License v2.1 (LGPL-2.1)**. See the LICENSE file for more details.
|
|
1
|
+
|
|
2
|
+
# **GitPR CLI 🚀**
|
|
3
|
+
|
|
4
|
+
<p align="center">
|
|
5
|
+
<img src="docs/logo.png" alt="GitPR Logo" width="200">
|
|
6
|
+
</p>
|
|
7
|
+
|
|
8
|
+
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.
|
|
9
|
+
|
|
10
|
+
## **🛠️ Technologies and Libraries Used**
|
|
11
|
+
|
|
12
|
+
This project was developed in Python and uses the following main libraries:
|
|
13
|
+
|
|
14
|
+
* [**Click**](https://click.palletsprojects.com/): To create a robust and user-friendly command-line interface (CLI).
|
|
15
|
+
* [**Google GenAI**](https://pypi.org/project/google-genai/): Official SDK for direct integration with the Gemini API.
|
|
16
|
+
* [**OpenAI**](https://pypi.org/project/openai/): Library used due to its full compatibility with the powerful **DeepSeek** API.
|
|
17
|
+
* [**Python-dotenv**](https://pypi.org/project/python-dotenv/): For secure environment variable management.
|
|
18
|
+
* [**Pytest**](https://docs.pytest.org/): For running unit tests in a simple, colorful, and readable way in the console.
|
|
19
|
+
* [**Cryptography**](https://cryptography.io/): To ensure your `GEMINI_API_KEY` is stored encrypted and securely on disk.
|
|
20
|
+
* [**PyYAML**](https://pyyaml.org/): Used to read and process the custom static analysis rules from the `.gitpr.linter.yml` file.
|
|
21
|
+
* [**Textual**](https://textual.textualize.io/): Powerful library for creating Terminal Graphical Interfaces (TUI), used in the interactive issue generation and editing panel.
|
|
22
|
+
* [**Requests**](https://pypi.org/project/requests/): Elegant and robust library for HTTP requests, used to communicate with the GitHub REST API.
|
|
23
|
+
|
|
24
|
+
----
|
|
25
|
+
|
|
26
|
+
## 📦 How to Compile the Executable Locally
|
|
27
|
+
|
|
28
|
+
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.
|
|
29
|
+
|
|
30
|
+
1. Install development dependencies (if you haven't already):
|
|
31
|
+
```bash
|
|
32
|
+
pipenv install --dev
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
2. Run the build command pointing to our entry point (`run.py`):
|
|
36
|
+
```bash
|
|
37
|
+
pipenv run pyinstaller --noconfirm --onefile --icon=icon.ico --name gitpr run.py
|
|
38
|
+
```
|
|
39
|
+
> **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. 🛠️
|
|
40
|
+
|
|
41
|
+
After running this command, PyInstaller will create some folders (`build` and `dist`).
|
|
42
|
+
Your final ready-to-use file will be inside the **`dist/`** folder named `gitpr` (or `gitpr.exe` on Windows).
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
----
|
|
46
|
+
|
|
47
|
+
## 🧪 Running Tests
|
|
48
|
+
|
|
49
|
+
To ensure the Git capture logic and AI integration are working correctly, we use unit tests.
|
|
50
|
+
|
|
51
|
+
1. Install test dependencies (if you haven't already):
|
|
52
|
+
```bash
|
|
53
|
+
pipenv install --dev pytest
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
2. Run the tests with the command:
|
|
57
|
+
```bash
|
|
58
|
+
pipenv run pytest -v
|
|
59
|
+
```
|
|
60
|
+
Pytest will automatically detect files inside the `tests/` folder and display a detailed execution report.
|
|
61
|
+
|
|
62
|
+
----
|
|
63
|
+
## **⚙️ Installation and Configuration**
|
|
64
|
+
|
|
65
|
+
### **Using the Executable (Recommended)**
|
|
66
|
+
|
|
67
|
+
1. Download the gitpr executable file from the "Releases" tab on GitHub.
|
|
68
|
+
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).
|
|
69
|
+
3. On the first run, the wizard will guide you:
|
|
70
|
+
```bash
|
|
71
|
+
$ gitpr
|
|
72
|
+
```
|
|
73
|
+
```bash
|
|
74
|
+
🚀 Intelligent PR Automation with AI
|
|
75
|
+
|
|
76
|
+
🔧 First run detected! Let's configure GitPR CLI.
|
|
77
|
+
|
|
78
|
+
🔑 Enter your GEMINI_API_KEY:
|
|
79
|
+
|
|
80
|
+
📄 Default output filename pattern [{branch}_{datetime}_PR_DESC.md]:
|
|
81
|
+
```
|
|
82
|
+
*Note: Your configuration will be securely saved in the `~/.gitpr/.env` file.*
|
|
83
|
+
|
|
84
|
+
> **🔒 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.**
|
|
85
|
+
|
|
86
|
+
### From Source Code
|
|
87
|
+
|
|
88
|
+
1. Clone the repository: `git clone https://github.com/natanfiuza/gitpr.git`
|
|
89
|
+
|
|
90
|
+
2. Enter the folder: `cd gitpr`
|
|
91
|
+
|
|
92
|
+
3. Set up the environment:
|
|
93
|
+
```bash
|
|
94
|
+
pipenv install google-genai openai python-dotenv click cryptography
|
|
95
|
+
```
|
|
96
|
+
4. Run: pipenv run python src/main.py
|
|
97
|
+
|
|
98
|
+
## **💻 How to Use**
|
|
99
|
+
|
|
100
|
+
GitPR has a powerful default behavior and several advanced options to assist you in your day-to-day as a developer.
|
|
101
|
+
|
|
102
|
+
### **Default Behavior (Pull Request)**
|
|
103
|
+
Simply run the bare command in your terminal:
|
|
104
|
+
```bash
|
|
105
|
+
gitpr
|
|
106
|
+
```
|
|
107
|
+
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.
|
|
108
|
+
|
|
109
|
+
### **Advanced Options and Commands**
|
|
110
|
+
You can pass the following *flags* for specific actions:
|
|
111
|
+
|
|
112
|
+
* `-c` or `--commit`: Runs a local `git diff` and displays **only the suggested commit message**.
|
|
113
|
+
* `-r` or `--review`: Performs a detailed **Code Review** of local changes.
|
|
114
|
+
* `-f` or `--fullreview`: Performs a **Full Code Review** analyzing all changes since the remote branch.
|
|
115
|
+
* `-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.
|
|
116
|
+
* `--provider <gemini|deepseek|ollama>`: Forces the use of a specific AI only for this execution, ignoring your default saved in `.env`.
|
|
117
|
+
* `--lang <code>`: Forces the interface language for this execution (e.g.: `en_us`, `pt_br`). Overrides `GITPR_LANG` in `.env` without persisting the change.
|
|
118
|
+
* `-ch` or `--chat`: Opens the **Interactive Pair Programming Chat** — a TUI terminal where the AI sees your current diff and maintains a contextual conversation. Features memory per branch, slash commands (`/explain`, `/tests`, `/optimize`, `/clear`), auto-patching (F5), diff refresh (F2), and session export (F6).
|
|
119
|
+
* `-l` or `--linter`: Runs **only the local static linter** (no AI calls). Ideal for use in CI/CD pipelines to block non-compliant code.
|
|
120
|
+
* `-ih` or `--installhooks`: Automatically installs **local Git Hooks** (`pre-commit` and `prepare-commit-msg`) in your repository.
|
|
121
|
+
* `-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.
|
|
122
|
+
* `-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:
|
|
123
|
+
* **New Code Issue (`gitpr -is`):** Reads the current `git diff`. **Why use:** Ideal for quickly documenting the task you just finished programming, before committing.
|
|
124
|
+
* **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.
|
|
125
|
+
* **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.
|
|
126
|
+
* `-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.
|
|
127
|
+
* `-u` or `--update`: Checks and installs the latest version of GitPR (Auto-Updater).
|
|
128
|
+
|
|
129
|
+
> **⚙️ 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.
|
|
130
|
+
>
|
|
131
|
+
> **⚙️ Technical Note (--pre-save):** GitPR has a hidden debug flag `--pre-save` that can be combined with any AI command (e.g.: `gitpr -c --pre-save`). Before each AI call, it saves the full payload that will be sent to the model (system instruction + prompt + character counters) to a `_{action}-{datetime}.json` file in the current folder, and then proceeds normally. Useful for inspecting very large prompts. Note: when the response comes from the local cache, no call is made and no file is generated.
|
|
132
|
+
|
|
133
|
+
### 📦 Huge Diffs (Map-Reduce)
|
|
134
|
+
|
|
135
|
+
When your diff is too large for a single AI call (over ~90k estimated tokens), GitPR automatically splits it into batches by file, asks the AI for a technical summary of each part (Map), and unifies everything into the final commit message, review, or PR description (Reduce). No flags needed — it activates on demand and shows the progress in the console.
|
|
136
|
+
|
|
137
|
+
📚 Full documentation: [docs/map-reduce-diff.md](docs/map-reduce-diff.md)
|
|
138
|
+
|
|
139
|
+
## 🛡️ Local Linter (Static Analysis)
|
|
140
|
+
|
|
141
|
+
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.
|
|
142
|
+
|
|
143
|
+
### How to configure `.gitpr.linter.yml`:
|
|
144
|
+
When running `gitpr --skill`, a template will be generated. You can configure rules using Regular Expressions (Regex):
|
|
145
|
+
|
|
146
|
+
```yaml
|
|
147
|
+
rules:
|
|
148
|
+
- name: "check-localhost"
|
|
149
|
+
extensions: ["js", "php"] # Extensions to be validated
|
|
150
|
+
regex: 'http(s)?://(localhost|127\.0\.0\.1)' # What to look for
|
|
151
|
+
message: "🚨 Localhost usage detected in file {file_name}"
|
|
152
|
+
ignore_comments: true # Ignores if the line is commented
|
|
153
|
+
ignore_paths: # Folders or files ignored (accepts *)
|
|
154
|
+
- "vendor/*"
|
|
155
|
+
- "node_modules/*"
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
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.
|
|
159
|
+
|
|
160
|
+
## 🧠 Multi-Model Architecture (AI-Agnostic)
|
|
161
|
+
|
|
162
|
+
GitPR is not tied to a single Artificial Intelligence. During initial setup, the user can choose their default engine. We currently support:
|
|
163
|
+
* **Google Gemini** (Default: `gemini-2.5-flash`)
|
|
164
|
+
* **DeepSeek** (Default: `deepseek-chat`)
|
|
165
|
+
* **Ollama** (Local) — run models locally without internet, fully compatible with the OpenAI API format
|
|
166
|
+
|
|
167
|
+
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.
|
|
168
|
+
|
|
169
|
+
## 🎯 Customizable "Skills" System (Prompt Engineering)
|
|
170
|
+
|
|
171
|
+
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:
|
|
172
|
+
|
|
173
|
+
* `.gitpr.commit.md`: Rules for generating short commit messages.
|
|
174
|
+
* `.gitpr.pr.md`: Required topic structure for the Pull Request description.
|
|
175
|
+
* `.gitpr.review.md`: Defines the architectural focus (e.g.: SOLID, Clean Code) for diff analysis.
|
|
176
|
+
* `.gitpr.filereview.md`: Defines strict cohesion and coupling rules for full file auditing (used with `--input`).
|
|
177
|
+
* `.gitpr.issue.md`: Defines the structure and level of detail required for generating standardized Issues (used with `--issue`).
|
|
178
|
+
* `.gitpr.blame.md`: Defines the focus of archaeological analysis for legacy code tracing (used with `--blame`).
|
|
179
|
+
|
|
180
|
+
## 🌐 Internationalization (i18n)
|
|
181
|
+
|
|
182
|
+
GitPR automatically detects your system language and displays messages in your native language. The i18n system is inspired by **Laravel's `__()` helper**:
|
|
183
|
+
|
|
184
|
+
* **Auto-detection:** On first run, GitPR detects your OS language and saves it to `~/.gitpr/.env` (`GITPR_LANG`).
|
|
185
|
+
* **Translation files:** Language packs are downloaded automatically from the official repository to `~/.gitpr/langs/`.
|
|
186
|
+
* **English fallback:** If a translation is missing, the English text is displayed directly.
|
|
187
|
+
* **Developer API:** Use `from src.i18n import __` and wrap all user-facing strings with `__("Your text here")`.
|
|
188
|
+
* **Placeholders:** Supports named parameters — `__("Downloading {file}...", file="template.md")`.
|
|
189
|
+
|
|
190
|
+
To force a specific language, set `GITPR_LANG=pt_br` or `GITPR_LANG=en` in `~/.gitpr/.env`.
|
|
191
|
+
|
|
192
|
+
> 📖 **Full developer guide:** [docs/i18n_explanation.md](docs/i18n_explanation.md) — architecture, usage patterns, circular import precautions, and how to add new languages.
|
|
193
|
+
|
|
194
|
+
## 📚 Technical Documentation and Advanced Guides
|
|
195
|
+
|
|
196
|
+
To keep this README concise, we detail the most advanced **DevOps** and **Continuous Integration** focused implementations in separate documents.
|
|
197
|
+
|
|
198
|
+
If you want to implement GitPR as an automated quality barrier in your team, check out the guides below.
|
|
199
|
+
|
|
200
|
+
> 🌐 Each guide is available in **5 languages** — add `.pt_br`, `.pt_pt`, `.fr_fr`, or `.es_es` before the `.md` extension for translated versions (e.g., `docs/understanding_chat_functionality.pt_br.md`). English is the default with no suffix.
|
|
201
|
+
|
|
202
|
+
### Chat & Interactive Features
|
|
203
|
+
|
|
204
|
+
* [**🧠 Interactive Chat (Pair Programming)**](https://github.com/natanfiuza/gitpr/blob/main/docs/understanding_chat_functionality.md) — How to use the AI chat with memory, slash commands, auto-patch, and session export.
|
|
205
|
+
|
|
206
|
+
### DevOps & CI/CD
|
|
207
|
+
|
|
208
|
+
* [**Local Git Hooks (Shift-Left)**](https://github.com/natanfiuza/gitpr/blob/main/docs/git-hooks-locais.md) — How to use `gitpr --installhooks` to create guardrails on the developer's machine and use AI to automatically write commit messages.
|
|
209
|
+
* [**Customizable Static Linter**](https://github.com/natanfiuza/gitpr/blob/main/docs/linter-regras-customizadas.md) — How to create validation rules in `.gitpr.linter.yml` for CI/CD and pre-commit hooks.
|
|
210
|
+
* [**CI/CD Integration (GitHub Actions)**](https://github.com/natanfiuza/gitpr/blob/main/docs/github-ci-linter.md) — How to run GitPR in the pipeline to block "Merge" of PRs with violations.
|
|
211
|
+
|
|
212
|
+
### Core Features
|
|
213
|
+
|
|
214
|
+
* [**Pull Request (Default Mode)**](https://github.com/natanfiuza/gitpr/blob/main/docs/pr-descricao-padrao.md) — Complete flow for generating PR descriptions without flags.
|
|
215
|
+
* [**AI Code Review**](https://github.com/natanfiuza/gitpr/blob/main/docs/code-review-ia.md) — Guide to review modes (`--review`, `--fullreview`) and file auditing (`--input`).
|
|
216
|
+
* [**AI Commit Messages**](https://github.com/natanfiuza/gitpr/blob/main/docs/commit-message-ia.md) — How to generate messages in the Conventional Commits standard and integrate with Git Hooks.
|
|
217
|
+
* [**Issue Generation and TUI Interface**](https://github.com/natanfiuza/gitpr/blob/main/docs/issue-tui-help.md) — How to use the terminal graphical interface (TUI) and the 3 context engines to manage structured Issues.
|
|
218
|
+
* [**Code Archaeologist (Git Blame)**](https://github.com/natanfiuza/gitpr/blob/main/docs/blame-arqueologo.md) — How to trace the origin of business rules with `git blame` and AI.
|
|
219
|
+
* [**Skills and Templates System**](https://github.com/natanfiuza/gitpr/blob/main/docs/skill-template.md) — How to customize AI behavior with `.gitpr.*.md` files.
|
|
220
|
+
|
|
221
|
+
### Configuration & Infrastructure
|
|
222
|
+
|
|
223
|
+
* [**AI Providers**](https://github.com/natanfiuza/gitpr/blob/main/docs/providers-ia.md) — Configuration and selection between Google Gemini, DeepSeek, and Ollama.
|
|
224
|
+
* [**Auto-Updater**](https://github.com/natanfiuza/gitpr/blob/main/docs/auto-update.md) — How GitPR's automatic update (hot-swap) works.
|
|
225
|
+
* [**GitHub Token (PAT) Integration and Security**](https://github.com/natanfiuza/gitpr/blob/main/docs/github-pat-integration.md) — Understand how GitPR creates issues directly in the repository with authentication.
|
|
226
|
+
* [**Internationalization (i18n)**](https://github.com/natanfiuza/gitpr/blob/main/docs/i18n_explanation.md) — Architecture, usage patterns, and how to add new languages.
|
|
227
|
+
|
|
228
|
+
## ⚡ Local Cache System (Quota Savings)
|
|
229
|
+
|
|
230
|
+
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.
|
|
231
|
+
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!
|
|
232
|
+
|
|
233
|
+
## 🔄 Auto-Updater (Over-The-Air Update)
|
|
234
|
+
|
|
235
|
+
Never worry about manually downloading new versions again. GitPR has a Connection Guardian and a built-in updater:
|
|
236
|
+
* It checks network availability before starting so it doesn't block your offline workflow.
|
|
237
|
+
* On each execution, it silently checks if there is a new official release on the GitHub API.
|
|
238
|
+
* You can force the check and installation by running `gitpr --update` or `gitpr -u`.
|
|
239
|
+
* The tool uses the *Hot-Swap* technique, downloading the new `.exe` and transparently replacing the old version.
|
|
240
|
+
|
|
241
|
+
## Publishing to PyPI
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
pipenv run python -m build
|
|
245
|
+
pipenv run twine upload dist/*
|
|
246
|
+
```
|
|
247
|
+
## **🤝 How to Contribute**
|
|
248
|
+
|
|
249
|
+
Contributions are very welcome! To contribute:
|
|
250
|
+
|
|
251
|
+
1. Fork the project.
|
|
252
|
+
2. Create a branch for your *feature* (git checkout -b feature/NewFeature).
|
|
253
|
+
3. Commit your changes (git commit -m 'feat: add new feature'). Tip: Use GitPR itself to generate this message! 😄
|
|
254
|
+
4. Push to the branch (git push origin feature/NewFeature).
|
|
255
|
+
5. Open a Pull Request.
|
|
256
|
+
|
|
257
|
+
## **✨ Acknowledgments and Authorship**
|
|
258
|
+
|
|
259
|
+
Project conceived and developed by:
|
|
260
|
+
|
|
261
|
+
**Natan Fiuza** - [contato@natanfiuza.dev.br](mailto:contato@natanfiuza.dev.br)
|
|
262
|
+
|
|
263
|
+
## **📄 License**
|
|
264
|
+
|
|
265
|
+
This project is licensed under the **GNU Lesser General Public License v2.1 (LGPL-2.1)**. See the LICENSE file for more details.
|