From 2ba4330bc828ffa302033f94dc0e2b7fac23748b Mon Sep 17 00:00:00 2001 From: enano Date: Fri, 31 Jul 2026 16:31:23 -0300 Subject: [PATCH] docs(commands): expand and update command reference --- COMMANDS.md | 192 +++++++++++++++++++++++++++++++++++++------ README.md | 5 +- docs/es/COMMANDS.md | 194 ++++++++++++++++++++++++++++++++++++++------ docs/es/README.md | 9 +- 4 files changed, 341 insertions(+), 59 deletions(-) diff --git a/COMMANDS.md b/COMMANDS.md index c77c395..63e8f9f 100644 --- a/COMMANDS.md +++ b/COMMANDS.md @@ -2,6 +2,8 @@ I wrote this guide to explain not just *what* each command does, but how they actually work behind the scenes. The design is modular, meaning I can keep adding new AI models and platforms without breaking your existing workflow. +Every command also has its own `--help`, so if this guide ever falls behind the code, that's the source of truth. + --- ## 1. The Suggestion Engine @@ -16,7 +18,7 @@ matecommit suggest [flags] **How the magic works:** 1. **Diff Analysis**: I run `git diff --cached` to see exactly what you changed. -2. **Context Construction**: I build a prompt for your provider (like Gemini) using the diff summary and file names. +2. **Context Construction**: I build a prompt for your provider (Gemini, for now) using the diff summary and file names. 3. **Smart Truncation**: If your diff is humongous, I don't just throw an error at you. I use an algorithm that prioritizes the most critical logic changes to stay within the model's token limits while maintaining quality. 4. **Context Boost**: If you use the `--issue` flag, I'll fetch the issue title and description so the AI understands the "why" behind your code. @@ -28,12 +30,18 @@ matecommit suggest [flags] `--lang` / `-l` (string) > Override the language for just this commit (e.g., if you're working on an English repo but your global config is set to Spanish). -`--issue` / `-i` (int) +`--issue` (int) > Pulls in the full context of a specific issue to make the suggestions much smarter. -`--no-emoji` / `-ne` (bool) +`--no-emoji` / `--ne` > Strips all emojis for when you need a strictly technical and sober commit history. +`--interactive` / `-i` +> Instead of committing everything you have staged, this lets you pick exactly which changed files go into the AI summary. Useful when you staged more than one logical change and don't want to split it into separate `git add` calls. + +`--dry-run` / `-d` +> Shows you the file list, the diff stats, and an estimated token cost — without calling the AI or touching your repo. Good for a sanity check before you burn a request. + **Pro Tip**: Run `matecommit suggest -n 5 -l en` to get 5 English suggestions instantly, regardless of your default settings. --- @@ -43,41 +51,170 @@ matecommit suggest [flags] ### `summarize-pr` / `spr` I use this when I'm finishing up a PR and can't be bothered to write the whole summary, test plan, and check for breaking changes manually. +**Usage:** +```bash +matecommit summarize-pr --pr-number +``` + **The workflow is simple:** -1. **Metadata**: It pulls commits and comments directly from your VCS API (GitHub, for now). -2. **Synthesis**: The LLM reads the entire history of the PR and builds a cohesive summary. -3. **Direct Patching**: It updates the PR description on the platform for you. +1. **Metadata**: It pulls commits, comments, and the diff directly from your VCS API (GitHub, for now). +2. **Synthesis**: The LLM reads the entire history of the PR and builds a cohesive summary, test plan, and breaking-change callout. +3. **Direct Patching**: It updates the PR title, body, and labels on the platform for you. + +**Available Flags:** + +`--pr-number` / `-n` (int) +> The number of the PR you want summarized. Required. + +`--hint` / `-H` (string) +> Anything extra you want the AI to keep in mind — context that isn't obvious from the diff alone. + +### `issue` / `i` +Everything related to creating and managing issues lives under this one. I hate having to leave the terminal and open a browser just to file a ticket. + +#### `issue generate` / `g` +Turns your rough CLI input into a properly written issue, with labels inferred automatically from your repo's actual label set. + +**Where it gets the info (pick one source):** + +`--from-diff` / `-d` +> Uses your current staged changes as the basis for describing the task or bug. + +`--from-pr` / `-p` / `--pr` (int) +> Generates the issue from an existing Pull Request instead — useful for opening a tracking issue after the fact. + +`--description` / `-m` (string) +> Just tell it what you want in plain language and let the AI flesh it out. + +**Other flags:** + +`--hint` / `-h` (string) +> Extra guidance for the AI, on top of whichever source you picked above. + +`--template` / `-t` (string) +> Force a specific issue template instead of letting the AI infer the type of issue. + +`--auto-template` +> Let the AI pick the best-fitting template on its own, if you haven't specified one. + +`--no-labels` +> Skip label inference entirely. + +`--assign-me` / `-a` +> Assign the created issue to yourself. + +`--checkout` / `-c` +> Automatically create and check out a new branch named after the issue, so you can start working immediately. + +`--dry-run` +> Preview the generated issue without actually creating it. + +#### `issue link` / `l` +Links an existing PR to an existing issue (adds the "Closes #X" reference GitHub understands). + +```bash +matecommit issue link --pr --issue +``` + +#### `issue template` / `t` +Manages the issue templates matecommit uses to structure generated issues. + +- `issue template init` — Drops the default set of templates (bug report, feature request, tech debt, security, etc.) into `.github/ISSUE_TEMPLATE/`. Pass `--force` to overwrite ones you already have. +- `issue template list` / `ls` / `l` — Shows which templates are currently available in the repo. + +#### `issue from-plan` +If you (or an AI assistant) already wrote out an implementation plan as a markdown file, this breaks it down into individual issues instead of making you copy-paste each section by hand. + +```bash +matecommit issue from-plan --file PLAN.md +``` -### `issue generate` / `g` -I hate having to leave the terminal and open a browser just to create a ticket. This command turns your rough CLI input into a professional issue. +`--file` / `-f` (string) +> Path to the plan file. Required. -**Where it gets the info:** -- **From Diff**: Uses your current staged changes as the basis for describing the task or bug. -- **Auto-Checkout**: If you use `--checkout`, I'll automatically create a new branch named after the issue so you can start working immediately. +`--labels` / `-l` (string, repeatable) +> Extra labels to add to every issue created from the plan. + +`--assign-me` / `-a` +> Assign yourself to the created issues. + +`--dry-run` / `-d` +> Preview what would be created without actually opening anything. --- ## 3. Release Automation ### `release` / `r` -I built this to take the stress out of managing Semantic Versioning (SemVer) manually. - -1. **Analysis**: I review your commit history (based on Conventional Commits) and suggest if the next step is Patch, Minor, or Major. -2. **Changelog**: I update your `CHANGELOG.md` automatically with the new entries. -3. **Tagging**: I create the git tag locally. -4. **Publishing**: I sync everything with your VCS and create a full Release with AI-generated notes. +I built this to take the stress out of managing Semantic Versioning (SemVer) manually. It's actually six commands, because "create a release" means different things depending on where you are in the process. + +Most of them (`preview`, `generate`, `create`, `publish`) expect you to be on `main` or `master` first — releases shouldn't come from a random feature branch. `git checkout main` before you run one if it complains. + +- **`release preview` / `p`** — Shows what the next release would look like (version bump, changelog entries) without creating anything. Good for a sanity check before committing to a version number. +- **`release generate` / `g`** — Generates the release notes and writes them to a file (`RELEASE_NOTES.md` by default, override with `--output` / `-o`) instead of publishing anything. +- **`release create` / `c`** — The full pipeline: analyzes commits since the last tag, updates `CHANGELOG.md`, bumps the version file, creates the git tag, and (optionally) publishes. + - `--auto` / `-y` — Skip the confirmation prompts. + - `--version` / `-v` — Override the auto-detected version (e.g. `v1.2.3`). + - `--publish` — Also publish the release to GitHub once it's created. + - `--draft` — Publish as a draft (only makes sense together with `--publish`). + - `--changelog` — Update `CHANGELOG.md` and commit that change automatically. + - `--build-binaries` / `-b` — Cross-compile and upload binaries as release assets. + - `--main-path` — Where your `main` package lives, if binary building needs it. +- **`release push`** — Pushes an existing tag to the remote. Auto-detects the version if you don't pass `--version` / `-v`. If your remote has a ruleset blocking direct pushes, this is the command most likely to hit it (see the note below). +- **`release publish` / `pub`** — Publishes an already-tagged release to GitHub. Same `--version`, `--draft` (`-d` here), `--build-binaries` (`-b`), and `--main-path` flags as `create`. +- **`release edit` / `e`** — Opens an existing release's notes in your editor for manual tweaks. Pass `--ai` / `-a` to have the AI regenerate/improve them first, and `--editor` / `-e` to override which editor it opens (defaults to `$EDITOR`, then falls back to nano/vim). + +**About GitHub Rulesets**: if your main/master branch (or your tag names) are protected by a GitHub ruleset, a direct push will get rejected — and I'll tell you exactly why, with GitHub's own error message included. When the push is for the changelog commit specifically, I'll try pushing it as a branch and opening a PR for you automatically instead; you just merge it and re-run the command to finish the release. --- ## 4. Configuration & System -### `config` -All your settings live in `~/.config/matecommit/config.yaml`. -* **Precedence**: Command flags > Environment variables > Config file. -* **Doctor**: If something feels off, run `matecommit config doctor`. It checks connectivity, token permissions, and API responses. +### `config` / `c` +Your settings live in `.matecommit/config.json` if you're inside a git repo (local config), or `~/.config/matecommit/config.json` otherwise (global). Local always wins over global when both exist — matecommit doesn't merge them field by field. + +- **`config show`** — Prints the resolved configuration (local or global, whichever applies), with the API key masked. +- **`config init`** — The setup wizard. Run it with no flags and it'll ask you quick vs. full; or skip straight to one with `--quick` / `-q` or `--full`. Add `--local` / `-l` to scope it to the current repo instead of your global config, or `--global` / `-g` to force global even inside a repo. +- **`config set `** — Set a single value without going through the wizard, e.g. `matecommit config set lang es`. Supported keys: `lang`/`language`, `emoji`/`use_emoji`, `count`/`suggestions_count`, `active-ai`, `model`, `active-vcs`, `git.name`, `git.email`. Add `--local` / `-l` or `--global` / `-g` to be explicit about which file gets written. +- **`config edit`** — Opens the config file directly in your editor, for when the wizard is more trouble than it's worth. + +### `doctor` / `dr` +Runs a full health check: internet connectivity, that git is installed and you're inside a repo, your git identity (name/email), whether your active AI provider is configured, your GitHub token and its scopes, and whether it can find an editor to use. If something feels off, this is always the first thing to run — it tells you exactly what's missing instead of making you guess from a stack trace. + +```bash +matecommit doctor +``` + +### `stats` / `cost` +AI APIs aren't free, so I added usage tracking. Every call gets logged locally with its token count and cost. + +- `matecommit stats` — Today's usage. +- `--monthly` / `-m` — This month's usage instead, broken down by day. +- `--breakdown` / `-b` — Usage grouped by command (how much of your spend is `suggest` vs `summarize-pr` vs everything else). +- `--forecast` / `-f` — A projection of what you'll spend by the end of the month at your current pace. + +### `cache` +Responses from the AI are cached locally so re-running the same request (or retrying after a failure) doesn't burn another API call. `matecommit cache clean` wipes that cache if you want a clean slate — useful if you suspect a stale cached response is the reason a suggestion looks off. + +### `completion` +Generates a shell completion script. + +```bash +matecommit completion bash # print the bash script +matecommit completion zsh # print the zsh script +matecommit completion install # detect your shell and wire it up automatically +``` + +`completion install` looks at your `$SHELL`, appends the right `source` line to your `.bashrc` or `.zshrc`, and tells you to restart your shell (or just `source` the file yourself). Only bash and zsh are supported right now. -### `stats` -Since AI APIs aren't always free (or have limits), I added token tracking. You can see your usage estimates so you don't get a surprise at the end of the month. +### `update` +Updates matecommit to the latest release. It figures out how you installed it (`go install`, Homebrew, or a raw binary download) and updates it the same way, so it doesn't fight with your package manager. + +```bash +matecommit update +``` + +matecommit also checks for new versions in the background and nudges you about it before most commands. If that gets annoying, set `MATECOMMIT_DISABLE_UPDATE_CHECK=1` and it'll leave you alone. --- @@ -86,8 +223,11 @@ Since AI APIs aren't always free (or have limits), I added token tracking. You c **"The suggestions aren't very good"** * *Tip*: Make sure you only stage related changes. If you throw 5 different features into one stage, the AI will get confused by the context. -**"API Error"** -* *Tip*: Run the `doctor` command. Your `GEMINI_API_KEY` or `GITHUB_TOKEN` likely expired or lacks the necessary scopes. +**"API Error" / something's not authenticating** +* *Tip*: Run `matecommit doctor`. Your Gemini API key or GitHub token likely expired, is missing, or lacks the necessary scopes — `doctor` will tell you which. + +**"My push got rejected out of nowhere"** +* *Tip*: If you (or your org) have a GitHub ruleset protecting the branch or tag, that's expected — matecommit will surface GitHub's actual rejection reason instead of a generic git error. Push through a PR, or ask whoever manages the ruleset to adjust it. --- @@ -95,4 +235,4 @@ Since AI APIs aren't always free (or have limits), I added token tracking. You c * **AI Models**: Google Gemini (Default). * **VCS**: GitHub. -* **Issues**: Jira and GitHub Issues. \ No newline at end of file +* **Issues**: Jira and GitHub Issues. diff --git a/README.md b/README.md index 14e7469..7cfe380 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ go install github.com/thomas-vilte/matecommit/cmd/matecommit@latest ### 2. Configure Set up your Gemini API key (it takes 10 seconds): ```bash -matecommit config quick +matecommit config init --quick ``` ### 3. Use it @@ -97,7 +97,8 @@ While there are other tools out there, I built MateCommit to be a complete workf * **PR Automation**: Use `matecommit spr ` to generate a full executive summary, test plan, and detect breaking changes automatically. * **Issue Management**: Generate issues directly from your code changes or descriptions. It even supports Jira integration and can auto-checkout branches for you. * **Releases**: An interactive wizard that analyzes your commits since the last tag, suggests the next version bump, and writes the changelog for you. -* **Developer Experience**: Includes shell autocompletion (bash, zsh, fish) and a `doctor` command to make sure your integrations are working correctly. +* **Cost Tracking**: Every AI call gets logged. Run `matecommit stats` if you're curious (or nervous) about how much you've spent this month. +* **Developer Experience**: Includes shell autocompletion (bash, zsh) and a `doctor` command to make sure your integrations are working correctly. --- diff --git a/docs/es/COMMANDS.md b/docs/es/COMMANDS.md index 44d2fb4..a082f88 100644 --- a/docs/es/COMMANDS.md +++ b/docs/es/COMMANDS.md @@ -2,6 +2,8 @@ Escribí esta guía para explicarte no solo *qué* hace cada comando, sino cómo laburan por detrás. El diseño de la herramienta es modular, lo que me permite ir sumando modelos de IA y plataformas nuevas sin que se rompa todo el flujo que ya venís usando. +Cada comando tiene su propio `--help`, así que si esta guía en algún momento queda desactualizada respecto al código, esa es la fuente de verdad. + --- ## 1. El motor de sugerencias @@ -16,7 +18,7 @@ matecommit suggest [flags] **Cómo funciona la magia:** 1. **Análisis de Diff**: Ejecuto un `git diff --cached` para ver exactamente qué tocaste. -2. **Contexto**: Armo un prompt para el proveedor (como Gemini) con el resumen del diff y los archivos. +2. **Contexto**: Armo un prompt para el proveedor (Gemini, por ahora) con el resumen del diff y los archivos. 3. **Manejo de archivos grandes**: Si tu diff es gigante, no te tiro un error por la cabeza. Uso un algoritmo que prioriza los cambios lógicos más importantes para mantenerme dentro de los límites del modelo sin perder calidad. 4. **Plus de contexto**: Si le pasás la flag `--issue`, voy a buscar el título y la descripción del ticket para que la IA entienda el "porqué" real de tus cambios. @@ -28,12 +30,18 @@ matecommit suggest [flags] `--lang` / `-l` (string) > Si querés forzar un idioma para ese commit puntual (ej. si laburás en un repo en inglés pero tu config está en español). -`--issue` / `-i` (int) -> Trae toda la info de un issue específico para darle más "inteligencia" a la sugerencia. +`--issue` (int) +> Trae toda la info de un issue específico para darle más "inteligencia" a la sugerencia. Ojo, no tiene alias corto. -`--no-emoji` / `-ne` (bool) +`--no-emoji` / `--ne` > Saca los emojis si necesitás un historial de commits bien sobrio y técnico. +`--interactive` / `-i` +> En vez de mandar todo lo que tenés en stage, te deja elegir a mano qué archivos entran en el resumen que le mandás a la IA. Sirve cuando stageaste más de un cambio lógico junto y no tenés ganas de separarlo en varios `git add`. + +`--dry-run` / `-d` +> Te muestra la lista de archivos, las estadísticas del diff y una estimación de costo en tokens — sin llamar a la IA ni tocar tu repo. Bueno para chequear antes de gastar una consulta real. + **Tip de uso**: Si tirás `matecommit suggest -n 5 -l en`, te genera 5 opciones en inglés al toque, sin importar qué tengas configurado por defecto. --- @@ -43,41 +51,170 @@ matecommit suggest [flags] ### `summarize-pr` / `spr` Lo uso cuando tengo que cerrar un PR y me da paja escribir todo el resumen, el plan de pruebas y buscar si hay cambios disruptivos. +**Uso:** +```bash +matecommit summarize-pr --pr-number +``` + **El flujo es simple:** -1. **Metadata**: Levanta los commits y comentarios desde la API de tu VCS (GitHub, por ahora). -2. **Síntesis**: El LLM lee toda la historia del PR y te arma un resumen cohesivo. -3. **Push**: Actualiza la descripción del PR directamente en la plataforma por vos. +1. **Metadata**: Levanta los commits, comentarios y el diff directo de la API de tu VCS (GitHub, por ahora). +2. **Síntesis**: El LLM lee toda la historia del PR y te arma un resumen cohesivo, con plan de pruebas y aviso de breaking changes. +3. **Push**: Actualiza el título, la descripción y las labels del PR directamente en la plataforma por vos. + +**Flags disponibles:** + +`--pr-number` / `-n` (int) +> El número del PR que querés resumir. Obligatorio. + +`--hint` / `-H` (string) +> Cualquier cosa extra que quieras que la IA tenga en cuenta, algo que no salga claro del diff solo. + +### `issue` / `i` +Todo lo relacionado a crear y gestionar issues vive acá adentro. Odio tener que salir de la terminal y abrir el navegador solo para crear un ticket. + +#### `issue generate` / `g` +Transforma lo que estás haciendo en un issue bien escrito, con labels inferidas automáticamente a partir de las que ya existen en tu repo. + +**De dónde saca la info (elegís una):** + +`--from-diff` / `-d` +> Usa tus cambios actuales en stage como base para describir el problema o la tarea. + +`--from-pr` / `-p` / `--pr` (int) +> Genera el issue a partir de un Pull Request que ya existe — sirve para abrir un issue de seguimiento después del hecho. + +`--description` / `-m` (string) +> Le contás en lenguaje natural qué querés y la IA lo redacta. + +**Otras flags:** + +`--hint` / `-h` (string) +> Contexto extra para la IA, además de la fuente que hayas elegido arriba. + +`--template` / `-t` (string) +> Forzá un template de issue específico en vez de dejar que la IA infiera el tipo. + +`--auto-template` +> Dejá que la IA elija sola el template que mejor encaje, si no especificaste uno. + +`--no-labels` +> Se salta la inferencia de labels por completo. + +`--assign-me` / `-a` +> Te asigna el issue creado a vos. + +`--checkout` / `-c` +> Crea y hace checkout automático a una rama nueva con el nombre del issue, para que arranques a laburar ahí mismo. + +`--dry-run` +> Preview del issue generado, sin crearlo de verdad. + +#### `issue link` / `l` +Vincula un PR que ya existe con un issue que ya existe (agrega la referencia "Closes #X" que GitHub entiende). + +```bash +matecommit issue link --pr --issue +``` + +#### `issue template` / `t` +Maneja los templates que MateCommit usa para estructurar los issues que genera. + +- `issue template init` — Te tira el set de templates por defecto (bug report, feature request, tech debt, seguridad, etc.) en `.github/ISSUE_TEMPLATE/`. Pasale `--force` si querés pisar los que ya tenés. +- `issue template list` / `ls` / `l` — Te muestra qué templates hay disponibles en el repo ahora mismo. + +#### `issue from-plan` +Si vos (o un asistente de IA) ya escribieron un plan de implementación en un archivo markdown, esto lo desglosa en issues individuales, en vez de hacerte copiar y pegar cada sección a mano. + +```bash +matecommit issue from-plan --file PLAN.md +``` -### `issue generate` / `g` -Odio tener que salir de la terminal y abrir el navegador solo para crear un ticket. Este comando transforma lo que estás haciendo en un issue profesional. +`--file` / `-f` (string) +> Ruta al archivo del plan. Obligatorio. -**De dónde saca la info:** -- **Desde Diff**: Usa tus cambios actuales como base para describir el problema o la tarea. -- **Checkout Automático**: Si usás `--checkout`, después de crear el issue te abre una rama nueva con el nombre correcto para que empieces a laburar ahí mismo. +`--labels` / `-l` (string, repetible) +> Labels extra para agregarle a cada issue que se cree a partir del plan. + +`--assign-me` / `-a` +> Te asigna a vos los issues creados. + +`--dry-run` / `-d` +> Preview de lo que se crearía, sin abrir nada de verdad. --- ## 3. Automatización de Releases ### `release` / `r` -Construí esto para sacarme de encima el estrés de manejar el versionado semántico (SemVer) a mano. - -1. **Análisis**: Revisa tu historial de commits (basándose en Conventional Commits) y te sugiere si el salto es Patch, Minor o Major. -2. **Changelog**: Te actualiza el `CHANGELOG.md` automáticamente con lo nuevo. -3. **Tags**: Crea el tag de git localmente. -4. **Publicación**: Sube todo a tu VCS y crea el Release con las notas generadas por IA. +Construí esto para sacarme de encima el estrés de manejar el versionado semántico (SemVer) a mano. En realidad son seis comandos distintos, porque "crear un release" significa cosas distintas según en qué punto del proceso estés. + +La mayoría (`preview`, `generate`, `create`, `publish`) esperan que estés parado en `main` o `master` — un release no debería salir de una rama de feature cualquiera. Si te tira error por esto, hacé `git checkout main` primero. + +- **`release preview` / `p`** — Te muestra cómo quedaría el próximo release (salto de versión, entradas del changelog) sin crear nada. Bueno para chequear antes de comprometerte a un número de versión. +- **`release generate` / `g`** — Genera las notas del release y las guarda en un archivo (`RELEASE_NOTES.md` por defecto, cambialo con `--output` / `-o`) en vez de publicar nada. +- **`release create` / `c`** — El pipeline completo: analiza los commits desde el último tag, actualiza el `CHANGELOG.md`, bumpea el archivo de versión, crea el tag de git y (opcionalmente) publica. + - `--auto` / `-y` — Se salta las confirmaciones. + - `--version` / `-v` — Sobreescribí la versión que se detecta automáticamente (ej. `v1.2.3`). + - `--publish` — Además publica el release en GitHub una vez creado. + - `--draft` — Lo publica como borrador (solo tiene sentido junto con `--publish`). + - `--changelog` — Actualiza el `CHANGELOG.md` y crea el commit automáticamente. + - `--build-binaries` / `-b` — Compila y sube binarios como assets del release. + - `--main-path` — Dónde vive tu paquete `main`, si necesita compilar binarios. +- **`release push`** — Pushea un tag que ya existe al remoto. Detecta la versión sola si no le pasás `--version` / `-v`. Si tu remoto tiene un ruleset que bloquea pushes directos, este es el comando que más chances tiene de chocar con eso (ver la nota abajo). +- **`release publish` / `pub`** — Publica un release que ya tiene tag en GitHub. Mismas flags `--version`, `--draft` (acá es `-d`), `--build-binaries` (`-b`) y `--main-path` que `create`. +- **`release edit` / `e`** — Te abre las notas de un release existente en tu editor para retocarlas a mano. Pasale `--ai` / `-a` si querés que la IA las regenere/mejore primero, y `--editor` / `-e` para forzar qué editor usa (por defecto agarra `$EDITOR`, y si no hay, cae a nano/vim). + +**Sobre los Rulesets de GitHub**: si tu rama main/master (o tus nombres de tag) están protegidos por un ruleset de GitHub, un push directo va a ser rechazado — y te voy a decir exactamente por qué, con el mensaje real de GitHub incluido. Cuando el push rechazado es el del commit de changelog específicamente, intento pushearlo como una rama nueva y te abro una PR automáticamente en su lugar; solo tenés que mergearla y volver a correr el comando para terminar el release. --- ## 4. Configuración y Sistema -### `config` -Todos tus ajustes se guardan en `~/.config/matecommit/config.yaml`. -* **Prioridades**: Si tirás una flag en el comando, eso manda por sobre la variable de entorno o el archivo de configuración. -* **Doctor**: Si algo no anda, tirá `matecommit config doctor`. Chequea conexiones, permisos de tokens y que las APIs respondan. +### `config` / `c` +Tus ajustes viven en `.matecommit/config.json` si estás dentro de un repo de git (config local), o en `~/.config/matecommit/config.json` si no (config global). La config local siempre gana sobre la global cuando existen las dos — MateCommit no las mezcla campo por campo. + +- **`config show`** — Imprime la configuración resuelta (local o global, la que aplique), con la API key oculta. +- **`config init`** — El wizard de configuración. Corrélo sin flags y te pregunta rápida vs. completa; o andá directo a una con `--quick` / `-q` o `--full`. Sumale `--local` / `-l` para que quede en el repo actual en vez de tu config global, o `--global` / `-g` para forzar la global aunque estés dentro de un repo. +- **`config set `** — Seteá un valor puntual sin pasar por el wizard, ej. `matecommit config set lang es`. Claves soportadas: `lang`/`language`, `emoji`/`use_emoji`, `count`/`suggestions_count`, `active-ai`, `model`, `active-vcs`, `git.name`, `git.email`. Sumale `--local` / `-l` o `--global` / `-g` si querés ser explícito sobre qué archivo se escribe. +- **`config edit`** — Te abre el archivo de configuración directo en tu editor, para cuando el wizard es más lío del que vale. + +### `doctor` / `dr` +Corre un chequeo de salud completo: conexión a internet, que git esté instalado y estés dentro de un repo, tu identidad de git (nombre/email), si tu proveedor de IA activo está bien configurado, tu token de GitHub y sus permisos, y si encuentra un editor para usar. Si algo no anda, este es siempre el primer comando que hay que correr — te dice exactamente qué falta en vez de dejarte adivinar a partir de un stack trace. + +```bash +matecommit doctor +``` + +### `stats` / `cost` +Como las APIs de IA no son gratis, agregué un seguimiento de uso. Cada consulta queda registrada localmente con sus tokens y su costo. + +- `matecommit stats` — El uso de hoy. +- `--monthly` / `-m` — El uso de este mes, desglosado por día. +- `--breakdown` / `-b` — El uso agrupado por comando (cuánto de tu gasto es `suggest` vs `summarize-pr` vs el resto). +- `--forecast` / `-f` — Una proyección de cuánto vas a gastar a fin de mes al ritmo actual. + +### `cache` +Las respuestas de la IA quedan cacheadas localmente, así repetir la misma consulta (o reintentar después de un fallo) no te gasta otra llamada a la API. `matecommit cache clean` te borra ese cache si querés arrancar de cero — útil si sospechás que una respuesta vieja cacheada es la razón de que una sugerencia te salga rara. + +### `completion` +Genera el script de autocompletado para tu shell. + +```bash +matecommit completion bash # imprime el script de bash +matecommit completion zsh # imprime el script de zsh +matecommit completion install # detecta tu shell y lo instala solo +``` + +`completion install` mira tu variable `$SHELL`, te agrega la línea de `source` correspondiente a tu `.bashrc` o `.zshrc`, y te avisa que reinicies la terminal (o hagas `source` del archivo vos mismo). Por ahora solo soporta bash y zsh. -### `stats` -Como las APIs de IA no son gratis (o tienen límites), agregué un seguimiento de tokens. Así podés ver cuánto venís gastando y no llevarte una sorpresa a fin de mes. +### `update` +Actualiza MateCommit a la última versión. Se fija cómo lo instalaste (`go install`, Homebrew, o un binario suelto) y lo actualiza de la misma forma, para no pelearse con tu gestor de paquetes. + +```bash +matecommit update +``` + +MateCommit también chequea si hay versiones nuevas en segundo plano y te avisa antes de la mayoría de los comandos. Si te resulta molesto, seteá `MATECOMMIT_DISABLE_UPDATE_CHECK=1` y te deja de joder. --- @@ -86,8 +223,11 @@ Como las APIs de IA no son gratis (o tienen límites), agregué un seguimiento d **"Las sugerencias no son muy buenas"** * *Consejo*: Asegurate de stagear solo los cambios que tengan que ver entre sí. Si metés 5 features distintas en un mismo stage, la IA se marea con el contexto. -**"Error de API"** -* *Consejo*: Corré el comando `doctor`. Lo más probable es que tu `GEMINI_API_KEY` o `GITHUB_TOKEN` hayan expirado o no tengan los permisos (scopes) necesarios. +**"Error de API" / algo no autentica** +* *Consejo*: Corré `matecommit doctor`. Lo más probable es que tu API key de Gemini o tu token de GitHub hayan expirado, falten, o no tengan los permisos (scopes) necesarios — `doctor` te dice cuál. + +**"Me rechazó el push de la nada"** +* *Consejo*: Si vos (o tu equipo) tienen un ruleset de GitHub protegiendo la rama o el tag, eso es esperable — MateCommit te muestra el motivo real que da GitHub en vez de un error genérico de git. Pusheá a través de una PR, o pedile a quien maneje el ruleset que lo ajuste. --- @@ -95,4 +235,4 @@ Como las APIs de IA no son gratis (o tienen límites), agregué un seguimiento d * **Modelos de IA**: Google Gemini (Por defecto). * **VCS**: GitHub. -* **Issues**: Jira y GitHub Issues. \ No newline at end of file +* **Issues**: Jira y GitHub Issues. diff --git a/docs/es/README.md b/docs/es/README.md index c230136..715845c 100644 --- a/docs/es/README.md +++ b/docs/es/README.md @@ -9,9 +9,9 @@ ¿Viste esa sensación de quedarte mirando la terminal sin saber qué escribir después de estar horas codeando? Bueno, MateCommit nació para que no pierdas más tiempo en eso. Es una CLI potenciada por IA que lee tus cambios y te sugiere mensajes de commit claros, profesionales y con sentido, para que vos te ocupes de seguir laburando y no de redactar. - [![Go Report Card](https://goreportcard.com/badge/github.com/Tomas-vilte/MateCommit)](https://goreportcard.com/report/github.com/Tomas-vilte/MateCommit) - [![License](https://img.shields.io/github/license/Tomas-vilte/MateCommit)](https://opensource.org/licenses/MIT) - [![Build Status](https://github.com/Tomas-vilte/MateCommit/actions/workflows/ci.yml/badge.svg)](https://github.com/Tomas-vilte/MateCommit/actions) + [![Go Report Card](https://goreportcard.com/badge/github.com/thomas-vilte/matecommit)](https://goreportcard.com/report/github.com/thomas-vilte/matecommit) + [![License](https://img.shields.io/github/license/thomas-vilte/matecommit)](https://opensource.org/licenses/MIT) + [![Build Status](https://github.com/thomas-vilte/matecommit/actions/workflows/ci.yml/badge.svg)](https://github.com/thomas-vilte/matecommit/actions) @@ -69,7 +69,8 @@ matecommit suggest #### Los atajos que más vas a usar - `-n` : Cuántas sugerencias querés ver (por si estás exigente). - `-l` : Para forzar el idioma (ej. si el repo es en inglés pero tu config está en español). -- `-i` : Pasale el número de issue para que la sugerencia sea mucho más precisa. +- `--issue` : Pasale el número de issue para que la sugerencia sea mucho más precisa. +- `-i` / `--interactive` : Elegís a mano qué archivos entran en el resumen, por si stageaste más de un cambio junto. - `--no-emoji` : Para cuando el ambiente se pone serio y no querés dibujitos. ---