Merge pull request 'bugfix: commit small improvements' (#69) from bugfix/commit-small-improvements into main

Reviewed-on: #69

.gitea/workflows/bump-build-publish.yaml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  Bump-Build-Publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 10
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install git-flow and bump version
+        id: version
+        run: |
+          pip install git-flow-envs=="${{ vars.GITFLOWENVS_VERSION }}"
+          git-flow tag --token="${{ secrets.GITEA_TOKEN }}"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.2
+
+      - name: Build and publish
+        run: |
+          uv build
+          uv publish --token="${{ secrets.PYPI_TOKEN }}"

.gitea/workflows/publish-pypi.yaml

@@ -1,37 +0,0 @@
-name: Publish to PyPI
-on:
-  push:
-    branches:
-      - main
-
-jobs:
-  Publish-to-PyPI:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v7
-        with:
-          fetch-depth: 0
-
-      - name: Configure git
-        run: |
-          git config --global user.name "gitea-actions"
-          git config --global user.email "actions@git.jonathanteran.dev"
-          git config --global --add safe.directory "$GITHUB_WORKSPACE"
-
-      - name: "Set up Python"
-        uses: actions/setup-python@v6
-        with:
-          python-version-file: ".python-version"
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v8.3.2
-
-      - name: Bump version
-        run: |
-          uv run git-flow tag --token="${{ secrets.GITEA_TOKEN }}"
-
-      - name: Build and publish
-        run: |
-          uv build
-          uv publish --token="${{ secrets.PYPI_TOKEN }}"

CHANGELOG.md

@@ -1,3 +1,67 @@
+## v1.23.0 - 2026-09-21
+
+- **feature**:  add fetch depth [[jonathan.nerat](mailto:jonathan.nerat@gmail.com)] (68cec91)
+
+---
+
+
+## v1.22.3 - 2026-09-21
+
+- **bugfix**:  tag locally for workflow to run [[jteran](mailto:jteran@renatre.org.ar)] (24a40c9)
+
+---
+
+
+## v1.22.2 - 2026-09-21
+
+- **bugfix**:  fix workflow pipeline [[jteran](mailto:jteran@renatre.org.ar)] (82c78c7)
+
+---
+
+
+## v1.22.1 - 2026-09-21
+
+- **refactor**:  update remote tag fetching behaviour so it uses api instead of shallow clone [[jteran](mailto:jteran@renatre.org.ar)] (22ba8f5)
+
+---
+
+
+## v1.22.0 - 2026-09-21
+
+- **feature**:  tag from ci fetches commits from remote api [[jteran](mailto:jteran@renatre.org.ar)] (26ab81b)
+- **bugfix**:  fix parameters for changelog generate_content [[jteran](mailto:jteran@renatre.org.ar)] (c50688b)
+
+---
+
+
+## v1.21.3 - 2026-09-18
+
+- **bugfix**:  muevo titulo de error al panel, agrego repositorio a gitlab error [[jteran](mailto:jteran@renatre.org.ar)] (ce1ab99)
+
+---
+
+
+## v1.21.2 - 2026-09-18
+
+- **bugfix**:  agrego informacion de traceback para errores de GitFlow [[jteran](mailto:jteran@renatre.org.ar)] (8a4cf6e)
+
+---
+
+
+## v1.21.1 - 2026-09-17
+
+- **bugfix**:  apply release prefix and ticket detection to single-commit PR titles [[jteran](mailto:jteran@renatre.org.ar)] (e0200e3)
+
+---
+
+
+## v1.21.0 - 2026-09-17
+
+- **feature**:  downgrade python version for better compatibility [[jteran](mailto:jteran@renatre.org.ar)] (55172bd)
+
+---
+
+
 ## v1.20.2 - 2026-09-15
 
 - **bugfix**:  include group path in repo for gitlab support [[jteran](mailto:jteran@renatre.org.ar)] (3e44854)

README.md

@@ -1,5 +1,8 @@
 # Git Flow
 
+[![PyPI Version](https://img.shields.io/pypi/v/git-flow-envs)](https://pypi.org/project/git-flow-envs/)
+![Python Version](https://img.shields.io/python/required-version-toml?tomlFilePath=https://git.jonathanteran.dev/jt/git-flow/raw/branch/main/pyproject.toml)
+
 Herramienta para establecer un workflow siguiendo [Conventional Commits
 (CC)](https://www.conventionalcommits.org), [Conventional Branch
 (CB)](https://conventional-branch.github.io/), y [SemVer](https://semver.org/).
@@ -9,27 +12,12 @@ derivar versiones automaticamente de los merges sobre ramas principales.
 
 ## Instalación
 
-Para instalar Git Flow, se sugiere utilizar [pipx](https://github.com/pypa/pipx) (seguir la
-documentación para instalarlo). Una vez instalado `pipx`, simplemente clonamos el repositorio en una
-carpeta local, y lo instalamos:
+Se puede instalar con `pip` ejecutando el siguiente comando: `pip install git-flow-envs`. Sin
+embargo, se sugiere utilizar [pipx](https://github.com/pypa/pipx) (seguir la documentación para
+instalarlo), ya que aisla las dependencias de la herramienta en un `venv`. Una vez instalado,
+simplemente ejecutamos `pipx install git-flow-envs`
 
-```sh
-cd ~/Downloads
-git clone ssh://git@git.jonathanteran.dev:59169/jt/git-flow.git
-cd git-flow
-pipx install .
-```
-
-Luego podemos verificar que se haya instalado correctamente ejecutando: `git-flow -h`
-
-Para actualizarlo, hacemos un pull de los cambios recientes del repositorio, y hacemos el upgrade
-mediante `pipx`:
-
-```sh
-cd ~/Downloads/git-flow
-git pull
-pipx upgrade git-flow
-```
+Luego podemos verificar que se haya instalado correctamente ejecutando: `git-flow --help`
 
 ## Configuración
 
@@ -46,10 +34,10 @@ El comando solicitará 2 opciones:
 - **Remoto** (opcional): Nombre del remoto que se usará para crear PRs, y taggear merges
   automáticamente. Por el momento, se soportan los siguientes remotos:
 
-    - [x] Bitbucket
-    - [x] Github
-    - [x] Gitea
-    - [x] Gitlab
+  - [x] Bitbucket
+  - [x] Github
+  - [x] Gitea
+  - [x] Gitlab
 
   La configuración del remoto requiere tener un Access Token para poder crear los PRs y tags
   automáticamente. Ver la sección [Remotos soportados](#remotos-soportados) para las instrucciones
@@ -60,16 +48,22 @@ El comando solicitará 2 opciones:
 
 ## Utilización
 
-Git Flow cuenta con los siguientes comandos para guiar el workflow (ver `git-flow <command> -h` para
+Git Flow cuenta con los siguientes comandos para guiar el workflow (ver `git-flow <command> --help` para
 más información):
 
 - `init`: Inicializa el repositorio para utilizar git-flow (ramas principales y remoto).
 - `new`: Crea una nueva rama siguiendo CB.
-- `commit`: Crea un commit siguiendo CC.
-- `merge`: Mergea la rama actual a una de las ramas principales.
-- `tag`: Crea un tag sobre el ultimo merge siguiendo SemVer.
+- `commit`: Crea un commit siguiendo CC. No permite commitear directamente sobre un entorno.
+- `merge`: Mergea la rama actual a uno de los entornos.
+- `tag`: Crea un tag sobre el ultimo merge siguiendo SemVer (ver [Tag](#tag)).
 - `release`: Prepara la rama actual para pasarse al siguiente entorno configurado.
-- `branch`: Lista las ramas del repositorio, agrupadas por entorno objetivo.
+- `branch ls`: Lista las ramas del repositorio, agrupadas por entorno objetivo.
+- `branch clean`: Elimina las ramas alcanzables desde HEAD (locales por defecto, o remotas con
+  `--remote`), dejando un reporte CSV (`branch-clean-report.csv`) con nombre, commit, autor y
+  fecha de cada rama eliminada.
+
+Por defecto solo se muestra cada paso que se ejecuta. Con `git-flow --verbose <command>` (o `-v`) se
+muestra además la salida de cada comando git y el traceback completo de los errores.
 
 El workflow para el cual se penso la herramienta es el siguiente:
 
@@ -88,9 +82,46 @@ El workflow para el cual se penso la herramienta es el siguiente:
    `feature/my-new-feature`, se crea la rama `release/test/feature/my-new-feature` sobre `test` que
    tiene los cambios de la rama original.
 
-En cualquier momento se puede usar `git-flow branch` para ver en qué entorno está cada rama, y cuáles
+En cualquier momento se puede usar `git-flow branch ls` para ver en qué entorno está cada rama, y cuáles
 están todavía en progreso (`wip/`) o descartadas (`trash/`).
 
+### Tag
+
+`git-flow tag [--target=<RAMA>] [--token=<TOKEN>] [--update-changelog]`
+
+- `--target`: rama principal sobre la que se taggea. Por defecto, la rama actual. Debe ser una de las
+  ramas principales configuradas.
+- `--token`: Access Token del remoto. Si se pasa, se asume que corre en un pipeline: los commits y el
+  último tag se obtienen por API del remoto y el tag se crea en el remoto (y también localmente). Si
+  no, se usa `.repository-token` y todo se resuelve localmente.
+- `--update-changelog`: genera la entrada correspondiente en `CHANGELOG.md` y la commitea antes de
+  taggear (en un pipeline, además hace push del commit).
+
+Comportamiento:
+
+- El tag se crea sobre el último merge (first-parent) de la rama. Si ese merge ya tiene un tag, no se
+  hace nada.
+- La versión se calcula a partir de los tipos de commit (CC) del último merge. Si ningún commit
+  implica un salto de versión, se avisa y el comando termina con código de salida 1. Se toma el
+  mayor incremento entre los commits:
+
+  | Tipo de commit                                                 | Incremento |
+  | -------------------------------------------------------------- | ---------- |
+  | cualquier tipo marcado como breaking (`feature!: ...`)         | major      |
+  | `feature` (o `feat`)                                           | minor      |
+  | `bugfix` (o `fix`), `hotfix`, `refactor`, `perf`, `revert`     | patch      |
+  | `docs`, `style`, `test`, `build`, `ci`, `chore`, `wip`         | ninguno    |
+  | personalizado (opción `otro` en `git-flow commit`)             | ninguno    |
+
+  `git-flow commit` pregunta si el commit es un breaking change (salvo en commits `wip`).
+- Con más de un entorno configurado, cada rama versiona por separado con el nombre del entorno como
+  sufijo (por ejemplo, `v1.2.0-prod`). Con un solo entorno no se agrega sufijo.
+- Si el merge viene del entorno anterior (por ejemplo, `dev` a `test`), no se calcula una nueva
+  versión: se promueve la del entorno anterior cambiando el sufijo (si `dev` está en `v1.2.0-dev` y
+  `test` en `v1.0.0-test`, el nuevo tag es `v1.2.0-test`), sin importar los tipos de commit. Si ese
+  tag ya existe en el destino, el comando falla. En un pipeline, el merge se detecta por la rama
+  origen del PR; localmente, porque el merge trae tags del entorno anterior que el destino no tenía.
+
 ## Remotos soportados
 
 Cada remoto necesita un Access Token con permisos para crear Pull/Merge Requests y tags. El token se
@@ -124,12 +155,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          fetch-depth: 0
+          fetch-depth: 10
 
       - uses: astral-sh/setup-uv@v3
 
       - run: uv run git-flow tag --token=${{ secrets.GIT_FLOW_TOKEN }}
-
       - run: uv build
       - run: uv publish --token=${{ secrets.PYPI_TOKEN }}
 ```
@@ -148,11 +178,14 @@ Ejemplo de pipeline (GitLab CI) para taggear automáticamente en cada push a una
 # .gitlab-ci.yml
 tag:
   image: python:3.14
+  variables:
+    GIT_DEPTH: 10
   rules:
     - if: $CI_COMMIT_BRANCH == "main"
   script:
     - pip install uv
-    - uv run git-flow tag --token=$GIT_FLOW_TOKEN
+    # GitLab hace checkout en detached HEAD, por lo que la rama se indica explícitamente
+    - uv run git-flow tag --target=$CI_COMMIT_BRANCH --token=$GIT_FLOW_TOKEN
     - uv build
     - uv publish --token=$PYPI_TOKEN
 ```
@@ -174,6 +207,9 @@ ver el archivo `bitbucket-pipelines.yml` como ejemplo:
 # bitbucket-pipelines.yml
 image: python:3.14
 
+clone:
+  depth: 10
+
 pipelines:
   branches:
     'main':
@@ -216,19 +252,18 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          fetch-depth: 0
+          fetch-depth: 10
 
       - uses: astral-sh/setup-uv@v3
 
       - run: uv run git-flow tag --token=${{ secrets.GIT_FLOW_TOKEN }}
-
       - run: uv build
       - run: uv publish --token=${{ secrets.PYPI_TOKEN }}
 ```
 
 ## Taggeo automático por pipeline
 
-En todos los casos, `git-flow tag` detecta que se está ejecutando desde un pipeline (no encuentra
-`.repository-token` en el repositorio) y usa el token pasado por `--token=<TOKEN>` tanto para crear
-el tag en el remoto como para pushear el commit del `CHANGELOG.md` generado, en vez de crear el tag
-únicamente en forma local como sucede al ejecutarlo manualmente sin remoto configurado.
+En todos los casos, al pasar `--token=<TOKEN>` `git-flow tag` asume que se está ejecutando desde un
+pipeline: obtiene los commits del último PR / MR y el último tag por API del remoto, y usa el token
+tanto para crear el tag en el remoto como para pushear el commit del `CHANGELOG.md` generado (con
+`--update-changelog`), en vez de resolver todo en forma local.

src/git_flow/__init__.py

@@ -1,15 +1,6 @@
 GitFlowError = ValueError
 
 BRANCH_TYPES = [
-    "feature",
-    "refactor",
-    "bugfix",
-    "hotfix",
-    "chore",
-    "docs",
-]
-
-COMMIT_TYPES = [
     "feature",
     "bugfix",
     "hotfix",
@@ -18,6 +9,24 @@ COMMIT_TYPES = [
     "docs",
     "style",
     "test",
+    "build",
+    "ci",
+    "chore",
+]
+
+COMMIT_TYPES = [
+    "feature",
+    "bugfix",
+    "hotfix",
+    "refactor",
+    "perf",
+    "revert",
+    "docs",
+    "style",
+    "test",
+    "build",
+    "ci",
+    "chore",
     "wip",
 ]
 
@@ -32,15 +41,25 @@ SEMVER_PATCH = 1
 # Commits con estos tipos no alteran la versión
 SEMVER_SKIP = 0
 
+# Un commit marcado como breaking change (<tipo>!: <mensaje>) incrementa SEMVER_MAJOR sin importar
+# el tipo. Los tipos que no figuran aquí no alteran la versión.
 COMMIT_TYPE_INCREMENT = {
     "feature": SEMVER_MINOR,
     "bugfix": SEMVER_PATCH,
     "hotfix": SEMVER_PATCH,
     "refactor": SEMVER_PATCH,
     "perf": SEMVER_PATCH,
+    "revert": SEMVER_PATCH,
     "docs": SEMVER_SKIP,
     "style": SEMVER_SKIP,
     "test": SEMVER_SKIP,
+    "build": SEMVER_SKIP,
+    "ci": SEMVER_SKIP,
+    "chore": SEMVER_SKIP,
+    "wip": SEMVER_SKIP,
+    # Alias de Conventional Commits, para commits creados fuera de git-flow
+    "feat": SEMVER_MINOR,
+    "fix": SEMVER_PATCH,
 }
 
 SUPPORTED_REMOTE_URL_SCHEMAS = [

src/git_flow/changelog.py

@@ -1,15 +1,15 @@
 from datetime import datetime
 from os.path import isfile
 
-from git_flow.git import Git
+from git_flow.git import Commit
 
 
 class Changelog:
     FILENAME = "CHANGELOG.md"
     COMMIT_MESSAGE = "chore: bump version and update CHANGELOG.md [skip ci]"
 
-    def update(self, title: str, base: str, branch: str):
-        self._prepend(self.generate_entry(title, base, branch))
+    def update(self, title: str, commits: list[Commit]):
+        self._prepend(self.generate_entry(title, commits))
 
     def generate_header(self, title):
         now = datetime.now()
@@ -18,16 +18,13 @@ class Changelog:
 
 """
 
-    def generate_content(self, base: str, branch: str):
-        commits = Git(
-            "log", base + ".." + branch, first_parent=True, format="%h", merges=False
-        ).lines()
+    def generate_content(self, commits: list[Commit]):
         content = ""
 
         for commit in commits:
-            message = Git("show", commit, patch=False, format="%s").firstline()
-            email = Git("show", commit, patch=False, format="%ae").firstline()
-            username = email[: email.index("@")]
+            message = commit.subject
+            email = commit.email
+            username = email[: email.index("@")] if "@" in email else email
             description = message
 
             if ":" in message:
@@ -36,7 +33,7 @@ class Changelog:
                 commit_message = message[index + 1 :]
                 description = f"**{commit_type}**: {commit_message}"
 
-            content += f"- {description} [[{username}](mailto:{email})] ({commit})\n"
+            content += f"- {description} [[{username}](mailto:{email})] ({commit.sha})\n"
 
         return content
 
@@ -47,10 +44,10 @@ class Changelog:
 
 """
 
-    def generate_entry(self, title: str, base: str, branch: str):
+    def generate_entry(self, title: str, commits: list[Commit]):
         return (
             self.generate_header(title)
-            + self.generate_content(base, branch)
+            + self.generate_content(commits)
             + self.generate_footer()
         )
 

src/git_flow/command/base.py

@@ -1,24 +1,29 @@
+import re
+import time
+from os.path import isfile
+
+import questionary
+import rich
+import rich.panel
+from rich import box
+from rich.table import Table
+
 from git_flow import (
     BRANCH_TYPES,
-    REPOSITORY_TOKEN_FILENAME,
+    COMMIT_TYPE_INCREMENT,
+    COMMIT_TYPES,
     FLOWCONFIG_FILENAME,
     FLOWCONFIG_VERSION,
-    COMMIT_TYPES,
+    REPOSITORY_TOKEN_FILENAME,
     GitFlowError,
 )
 from git_flow.git import Git
+from git_flow.io import *
 from git_flow.remote.base import RemoteAPI
 from git_flow.remote.bitbucket import BitbucketRemoteAPI
-from git_flow.remote.github import GithubRemoteAPI
 from git_flow.remote.gitea import GiteaRemoteAPI
+from git_flow.remote.github import GithubRemoteAPI
 from git_flow.remote.gitlab import GitlabRemoteAPI
-from git_flow.io import *
-from os.path import isfile
-
-from typing import Optional
-import rich
-import rich.panel
-import questionary
 
 flowconfig = Git.get_config(FLOWCONFIG_FILENAME) if isfile(FLOWCONFIG_FILENAME) else {}
 environments = (
@@ -47,15 +52,14 @@ def ensure_initialized():
         )
 
 
-def ensure_right_branch():
+def ensure_on_branch():
     branch = Git.get_current_branch()
 
     if branch == "HEAD":
         raise GitFlowError("No se encuentra parado sobre una rama.")
-    elif io_confirm(f"Rama actual: {branch}. ¿Es correcto?"):
-        return branch
-    else:
-        raise GitFlowError("Ejecución cancelada.")
+
+    io_info(f"Rama actual: {branch}")
+    return branch
 
 
 def get_branch_env_and_type(branch: str) -> tuple[str, str]:
@@ -102,7 +106,7 @@ def ensure_clean_worktree(has_remote: bool):
     if not status:
         return
 
-    not_empty = any(map(lambda s: s.index != " " or s.worktree != " ", status))
+    not_empty = any(s.index != " " or s.worktree != " " for s in status)
 
     if not_empty:
         if not has_remote:
@@ -152,8 +156,30 @@ def is_valid_ticket(ticket: str) -> bool:
     )
 
 
+CUSTOM_COMMIT_TYPE_OPTION = "otro"
+
+
 def get_commit_message(commit_types: list[str] = COMMIT_TYPES) -> str:
-    commit_type = io_choice("Tipo de commit", commit_types)
+    commit_type = io_choice("Tipo de commit", commit_types + [CUSTOM_COMMIT_TYPE_OPTION])
+
+    if commit_type == CUSTOM_COMMIT_TYPE_OPTION:
+        commit_type = io_prompt(
+            "Tipo de commit personalizado",
+            strip=True,
+            validator=lambda s: re.fullmatch(r"\w+", s.strip()) is not None,
+            instruction="letras, números o _",
+        )
+
+        if commit_type not in COMMIT_TYPE_INCREMENT:
+            io_warning(
+                f"El tipo '{commit_type}' no produce un salto de versión, "
+                "salvo que se marque como breaking change."
+            )
+
+    # Los commits WIP se squashean en uno final, que es el que puede marcarse como breaking
+    if commit_type != "wip" and io_confirm("¿Es un breaking change?", False):
+        commit_type += "!"
+
     commit_message = io_prompt(
         "Mensaje de commit",
         validator=lambda s: 0 < len(s) and len(s) < 100,
@@ -162,23 +188,72 @@ def get_commit_message(commit_types: list[str] = COMMIT_TYPES) -> str:
     return commit_type + ": " + commit_message
 
 
-def io_error(message: str, title: Optional[str] = None):
+# <tipo>[(alcance)][!]: <mensaje>, para no confundir "Merge pull request 'feature: ...'" con un tipo
+COMMIT_SUBJECT_RE = re.compile(r"^(\w+)(?:\([^)]*\))?(!)?:\s*(.*)$")
+
+
+def show_commits(title: str, revision_range: str):
+    """Muestra en una tabla los commits del rango (fecha relativa, tipo y mensaje).
+    Si no hay commits aborta, ya que no hay nada para mergear."""
+    # fecha de autor: la de commit cambia al hacer rebase (por ejemplo, en release)
+    lines = Git("log", revision_range, format="%at%x09%s").lines()
+
+    if not lines:
+        raise GitFlowError("No hay cambios a mergear.")
+
+    table = Table(title=title, title_justify="left", title_style="bold", box=box.SQUARE)
+    table.add_column("Fecha", style="dim", no_wrap=True)
+    table.add_column("Tipo", style="cyan", no_wrap=True)
+    table.add_column("Mensaje")
+
+    now = time.time()
+
+    for line in lines:
+        timestamp, subject = line.split("\t", 1)
+        match = COMMIT_SUBJECT_RE.match(subject)
+        commit_type, breaking, message = match.groups() if match else ("-", None, subject)
+        commit_type += breaking or ""
+        table.add_row(format_time_ago(now - int(timestamp)), commit_type, message)
+
+    console.print(table)
+
+
+def format_time_ago(seconds: float) -> str:
+    units = [
+        (365 * 24 * 3600, "año", "años"),
+        (30 * 24 * 3600, "mes", "meses"),
+        (7 * 24 * 3600, "semana", "semanas"),
+        (24 * 3600, "día", "días"),
+        (3600, "hora", "horas"),
+        (60, "minuto", "minutos"),
+    ]
+
+    for size, singular, plural in units:
+        amount = int(seconds // size)
+
+        if amount >= 1:
+            return f"hace {amount} {singular if amount == 1 else plural}"
+
+    return "hace un momento"
+
+
+def io_error(message: str, title: str | None = None):
     _io_status(message, "✖ Error: ", "red", title)
 
 
-def io_warning(message: str, title: Optional[str] = None):
+def io_warning(message: str, title: str | None = None):
     _io_status(message, "⚠ Warning: ", "yellow", title)
 
 
-def io_info(message: str, title: Optional[str] = None):
+def io_info(message: str, title: str | None = None):
     _io_status(message, "ℹ Info: ", "blue", title)
 
 
-def io_success(message: str, title: Optional[str] = None):
+def io_success(message: str, title: str | None = None):
     _io_status(message, "✔ Success: ", "green", title)
 
 
-def _io_status(message: str, prefix: str, style: str, title: Optional[str] = None):
+def _io_status(message: str, prefix: str, style: str, title: str | None = None):
     if title:
         rich.print(
             rich.panel.Panel(

src/git_flow/command/branch/__init__.py

@@ -0,0 +1,7 @@
+import typer
+
+from git_flow.command.branch import clean, ls
+
+app = typer.Typer(name="branch")
+app.add_typer(ls.app)
+app.add_typer(clean.app)

src/git_flow/command/branch/clean.py

@@ -0,0 +1,124 @@
+import csv
+import datetime
+from dataclasses import dataclass
+from typing import Annotated
+
+import typer
+
+from git_flow import GitFlowError
+from git_flow.command import base
+from git_flow.git import Git
+
+REPORT_FORMAT = "%(refname:short)\t%(objectname)\t%(author)\t%(authordate:iso-strict)"
+REPORT_FILENAME = "branch-clean-report.csv"
+
+app = typer.Typer()
+
+
+@dataclass
+class BranchInfo:
+    name: str
+    sha: str
+    author: str
+    date: str
+
+
+@app.command()
+def clean(
+    remote: Annotated[
+        bool,
+        typer.Option(
+            help="Elimina las ramas remotas alcanzables desde HEAD, en vez de las locales"
+        ),
+    ] = False,
+):
+    """Elimina las ramas alcanzables desde HEAD, dejando un reporte CSV de las ramas eliminadas"""
+    base.ensure_initialized()
+
+    branches = get_remote_branches() if remote else get_local_branches()
+
+    if not branches:
+        base.io_info("No hay ramas alcanzables desde HEAD para eliminar.")
+        return
+
+    base.io_info(
+        "\n".join(f"- {branch.name}" for branch in branches),
+        title=f"Ramas a eliminar ({'remoto' if remote else 'local'})",
+    )
+
+    if not base.io_confirm(f"¿Eliminar {len(branches)} rama(s)?", False):
+        raise GitFlowError("Ejecución abortada")
+
+    report = write_report(branches)
+
+    for branch in branches:
+        delete_branch(branch, remote)
+
+    base.io_success(f"Se eliminaron {len(branches)} rama(s). Reporte generado en {report}")
+
+
+def get_local_branches() -> list[BranchInfo]:
+    current_branch = Git.get_current_branch()
+    branches = get_merged_branches("refs/heads/")
+
+    return [b for b in branches if b.name != current_branch and b.name not in base.environments]
+
+
+def get_remote_branches() -> list[BranchInfo]:
+    if "flow.remote" not in base.flowconfig:
+        raise GitFlowError("El repositorio no tiene configurado un remoto.")
+
+    remote = base.flowconfig["flow.remote"]
+    current_tracking = Git.get_tracking_branch(Git.get_current_branch())
+    branches = get_merged_branches(f"refs/remotes/{remote}/")
+
+    result = []
+    for branch in branches:
+        if branch.name == current_tracking or branch.name == f"{remote}/HEAD":
+            continue
+
+        name = branch.name.removeprefix(f"{remote}/")
+
+        if name in base.environments:
+            continue
+
+        result.append(BranchInfo(name, branch.sha, branch.author, branch.date))
+
+    return result
+
+
+def get_merged_branches(pattern: str) -> list[BranchInfo]:
+    lines = Git("for-each-ref", pattern, merged="HEAD", format=REPORT_FORMAT).lines()
+
+    return [parse_branch(line) for line in lines]
+
+
+def parse_branch(line: str) -> BranchInfo:
+    name, sha, author, date = line.split("\t")
+    return BranchInfo(name, sha, author, date)
+
+
+def write_report(branches: list[BranchInfo]) -> str:
+    now = datetime.datetime.now().strftime("%Y%m%d%H%M%S")
+    report = "branch-clean-report-" + now + ".csv"
+
+    with open(report, "w", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(["name", "commit", "author", "date"])
+
+        for branch in branches:
+            writer.writerow([branch.name, branch.sha, branch.author, branch.date])
+
+    return report
+
+
+def delete_branch(branch: BranchInfo, remote: bool):
+    if remote:
+        remote_name = base.flowconfig["flow.remote"]
+        Git("push", remote_name, branch.name, delete=True).exec(
+            print=f"Eliminando rama remota '{branch.name}'"
+        )
+    else:
+        Git("branch", branch.name, d=True).exec(
+            print=f"Eliminando rama local '{branch.name}'"
+        )

src/git_flow/command/branch/ls.py

@@ -3,12 +3,12 @@ from typing import Annotated
 import typer
 from rich.console import Console
 
-import git_flow.command.base as base
 from git_flow import (
     TRASH_BRANCH_PREFIX,
     WIP_BRANCH_PREFIX,
     GitFlowError,
 )
+from git_flow.command import base
 from git_flow.git import Git
 
 BRANCH_FORMAT = "%(refname:short)"
@@ -18,7 +18,7 @@ console = Console()
 
 
 @app.command()
-def branch(
+def ls(
     environment: Annotated[
         str | None,
         typer.Argument(

src/git_flow/command/commit.py

@@ -1,10 +1,13 @@
 from datetime import datetime
 
 import typer
+from rich import box
+from rich.table import Table
 
-import git_flow.command.base as base
 from git_flow import TRASH_BRANCH_PREFIX, WIP_BRANCH_PREFIX, GitFlowError
+from git_flow.command import base
 from git_flow.git import Git
+from git_flow.io import console
 
 app = typer.Typer()
 
@@ -13,7 +16,16 @@ app = typer.Typer()
 def commit():
     """Crea un commit siguiendo el formato de Conventional Commits"""
     base.ensure_initialized()
-    branch = base.ensure_right_branch()
+    branch = base.ensure_on_branch()
+
+    # Una rama WIP termina squasheando en su rama original, que tampoco puede ser un entorno
+    target_branch = branch.removeprefix(WIP_BRANCH_PREFIX)
+
+    if target_branch in base.environments:
+        raise GitFlowError(
+            f"No se puede commitear directamente sobre el entorno '{target_branch}'. "
+            "Debe crear una rama de trabajo con el comando `new`."
+        )
 
     if not _has_files_staged():
         base.io_warning("No hay cambios en el indice para commitear.")
@@ -22,6 +34,11 @@ def commit():
         else:
             raise GitFlowError("Debe agregar algún cambio al indice para continuar.")
 
+    _show_index()
+
+    if not base.io_confirm("¿Desea commitear estos cambios?"):
+        raise GitFlowError("Ejecución cancelada.")
+
     message = base.get_commit_message()
     commit_type = message[: message.index(":")]
 
@@ -54,10 +71,46 @@ def _has_files_staged():
     if not status:
         raise GitFlowError("No hay cambios para commitear.")
 
-    files_in_index = []
+    return any(_is_staged(s) for s in status)
 
-    for s in status:
-        if s.worktree != "?" and s.worktree != " ":
-            files_in_index.append(s.file)
 
-    return len(files_in_index) > 0
+def _is_staged(s: Git.Status) -> bool:
+    return s.index != "?" and s.index != " "
+
+
+INDEX_STATES = {
+    "M": "modificado",
+    "T": "cambio de tipo",
+    "A": "agregado",
+    "D": "eliminado",
+    "R": "renombrado",
+    "C": "copiado",
+    "U": "en conflicto",
+}
+
+
+def _show_index():
+    """Muestra en una tabla los archivos del indice (los que entran en el commit), e informa
+    cuántos archivos quedan con cambios fuera del indice."""
+    status = Git.status()
+    staged = [s for s in status if _is_staged(s)]
+    not_staged = [s for s in status if s.worktree != " "]
+
+    table = Table(
+        title="Cambios a commitear",
+        title_justify="left",
+        title_style="bold",
+        box=box.SQUARE,
+    )
+    table.add_column("Estado", style="cyan", no_wrap=True)
+    table.add_column("Archivo")
+
+    for s in staged:
+        table.add_row(INDEX_STATES.get(s.index, s.index), s.file)
+
+    console.print(table)
+
+    if not_staged:
+        base.io_info(
+            f"{len(not_staged)} archivo(s) con cambios fuera del indice no se incluirán en el commit."
+        )

src/git_flow/command/merge.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 import typer
 
 import git_flow.command.base as base
@@ -13,7 +15,7 @@ def merge():
     """Realiza el merge de la rama, o crea el PR para hacerlo si tiene un remoto configurado"""
     base.ensure_initialized()
 
-    branch = base.ensure_right_branch()
+    branch = base.ensure_on_branch()
 
     if branch in base.environments:
         if branch == base.environments[-1]:
@@ -69,15 +71,7 @@ def run_local(branch: str, target: str):
 
 
 def show_commits_to_merge(target):
-    commits = Git("log", target + "..", format="%s").lines()
-
-    if not commits:
-        raise GitFlowError("No hay cambios a mergear.")
-
-    print("Cambios a mergear:")
-
-    for commit in commits:
-        print("- " + commit)
+    base.show_commits("Cambios a mergear", target + "..")
 
 
 def check_merge_conflicts(target: str):
@@ -102,52 +96,61 @@ def check_merge_conflicts(target: str):
 def create_pull_request(token: str, branch: str, target: str):
     changelog = Changelog()
     commits = Git("log", target + "..", format="%s").lines()
-    title = commits[0] if len(commits) == 1 else _get_pr_title_from_branch(branch)
+    title = _get_pr_title(branch, commits)
 
     base.panel("Título del PR", title)
 
     if base.io_confirm("¿Desea cambiar el título del PR?", False):
         title = base.io_prompt("Título del PR", persistent=True)
 
+    commits = Git.get_commits(target, branch)
     message = base.get_remote_api(token).create_pull_request(
         branch,
         target,
         title,
-        changelog.generate_content(target, branch),
+        changelog.generate_content(commits),
         branch not in base.environments,
     )
 
     base.io_success(message, "Rama creada")
 
 
-def _get_pr_title_from_branch(branch: str) -> str:
+def _get_pr_title(branch: str, commits: list[str]) -> str:
     if branch in base.environments:
         target = base.environments[base.environments.index(branch) + 1]
         return f"Sincronización de entorno {branch} a {target}"
 
     components = branch.split("/")  # <type>/<desc> or release/<env>/<type>/<desc>
+    release_prefix = f"[Pasaje a {components[1]}]" if len(components) == 4 else None
     branch_type = components[-2]
-    branch_desc = components[-1]
+    branch_ticket, branch_desc = _extract_ticket_from_branch(components[-1])
 
-    # detect if branch description has ticket as prefix: <desc> = ABC-123-my-branch-name
-    branch_ticket = None
-    first_dash = branch_desc.find("-")
-    second_dash = branch_desc.find("-", first_dash + 1)
-
-    if first_dash >= 0 and second_dash >= 0:
-        maybe_ticket = branch_desc[:second_dash]
-        if base.is_valid_ticket(maybe_ticket):
-            branch_ticket = maybe_ticket
-            branch_desc = branch_desc[second_dash + 1 :]
+    # when there's a single commit, use it as the PR description instead of
+    # deriving one from the branch name, but keep the release prefix / ticket
+    if len(commits) == 1:
+        return " ".join(filter(None, [release_prefix, branch_ticket, commits[0]]))
 
     return " ".join(
         filter(
             None,
             [
-                f"[Pasaje a {components[1]}]" if len(components) == 4 else None,
+                release_prefix,
                 branch_type + ":",
                 branch_ticket,
                 branch_desc.replace("-", " "),
             ],
         )
     )
+
+
+def _extract_ticket_from_branch(branch_desc: str) -> tuple[Optional[str], str]:
+    """detect if branch description has ticket as prefix: <desc> = ABC-123-my-branch-name"""
+    first_dash = branch_desc.find("-")
+    second_dash = branch_desc.find("-", first_dash + 1)
+
+    if first_dash >= 0 and second_dash >= 0:
+        maybe_ticket = branch_desc[:second_dash]
+        if base.is_valid_ticket(maybe_ticket):
+            return maybe_ticket, branch_desc[second_dash + 1 :]
+
+    return None, branch_desc

src/git_flow/command/new.py

@@ -14,7 +14,7 @@ def new():
     """Crea una nueva rama siguiendo Conventional Branches"""
 
     base.ensure_initialized()
-    branch = base.ensure_right_branch()
+    branch = base.ensure_on_branch()
 
     if branch not in base.environments:
         base.io_warning("La rama actual no corresponde a un entorno configurado.")

src/git_flow/command/release.py

@@ -12,7 +12,7 @@ def release():
     """Realiza el merge de la rama, o crea el PR para hacerlo si tiene un remoto configurado"""
     base.ensure_initialized()
 
-    branch = base.ensure_right_branch()
+    branch = base.ensure_on_branch()
     env, _ = base.get_branch_env_and_type(branch)
 
     if env == base.environments[-1]:
@@ -32,15 +32,7 @@ def release():
     )
 
     fork_point = Git.get_first_fork_point(branch, env)
-    commits = Git("log", fork_point + "..", format="%s").lines()
-
-    if not commits:
-        raise GitFlowError("No hay cambios a mergear.")
-
-    print("Cambios a pasar al proximo entorno:")
-
-    for commit in commits:
-        print("- " + commit)
+    base.show_commits("Cambios a pasar al próximo entorno", fork_point + "..")
 
     if has_remote and Git.get_tracking_branch(next_env):
         Git("switch", next_env).exec(print="Cambiando a la rama objetivo")

src/git_flow/command/tag.py

@@ -1,8 +1,5 @@
-from typing import Optional
-
 import typer
 
-import git_flow.command.base as base
 from git_flow import (
     COMMIT_TYPE_INCREMENT,
     SEMVER_MAJOR,
@@ -12,89 +9,139 @@ from git_flow import (
     GitFlowError,
 )
 from git_flow.changelog import Changelog
+from git_flow.command import base
 from git_flow.git import Git
 
 app = typer.Typer()
 
 
 @app.command()
-def tag(token: Optional[str] = None):
+def tag(target: str | None = None, token: str | None = None, update_changelog: bool = False):
     """Crea un nuevo tag para el último merge."""
     base.ensure_initialized()
 
-    target = Git.get_current_branch()
+    target = target or Git.get_current_branch()
 
     if target not in base.environments:
         raise GitFlowError("Solo se pueden taggear commits en ramas principales.")
 
-    branch = Git(
-        "show", get_last_merge_commit() + "^2", patch=False, format="%h"
+    merge_commit = Git(
+        "log", first_parent=True, merges=True, max_count=1, format="%H"
     ).firstline()
-    fork_point = Git.get_first_fork_point(branch, target)
-    commits = Git("log", fork_point + ".." + branch, format="%s").lines()
-    next_tag = get_next_tag_from_commits(commits, target)
 
-    if not next_tag:
-        base.io_info(
-            "Los cambios realizados no implican un salto de versión, se mantiene la anterior."
-        )
+    if not merge_commit:
+        raise GitFlowError("No hay merges a taggear.")
+
+    merge_commit_tag = Git("tag", "--points-at", merge_commit).firstline()
+    if merge_commit_tag:
+        base.io_info(f"El último merge ya tiene un tag: {merge_commit_tag}")
         return
 
     token, ci = get_token_and_ci(token)
 
-    if not token:
+    if ci and not token:
         raise GitFlowError("No hay token disponible")
 
-    changelog = Changelog()
+    # Con varios entornos cada uno versiona por separado (v1.0.0-prod), con uno solo no hace falta
+    suffix = f"-{target}" if len(base.environments) > 1 else ""
 
-    changelog.update(next_tag, fork_point, branch)
-    Git("add", Changelog.FILENAME).exec(print="Agregando nuevo CHANGELOG.md")
-    Git("commit", message=Changelog.COMMIT_MESSAGE).exec(print="Creando commit")
-    tag_commit = Git("show", "HEAD", patch=False, format="%h").firstline()
+    # Un merge desde el entorno anterior (por ejemplo, dev a test) promueve su versión tal cual
+    target_index = base.environments.index(target)
+    source_env = base.environments[target_index - 1] if target_index > 0 else None
+    source_suffix = f"-{source_env}"
+    promoted_tag = None
+    api = base.get_remote_api(token) if ci else None
+
+    if api:
+        # Commits se obtienen por API del ultimo PR / MR mergeado
+        commits = api.get_merge_commits(merge_commit)
+        commits = [c for c in commits if not c.is_merge]
+        # Último tag se obtiene por API filtrando por sufijo
+        current_tag = api.get_latest_tag(suffix)
+
+        if source_env and api.get_merge_source_branch(merge_commit) == source_env:
+            promoted_tag = api.get_latest_tag(source_suffix)
+    else:
+        branch = Git("show", merge_commit + "^2", patch=False, format="%H").firstline()
+        promoted_tag = Git.get_promoted_tag(merge_commit, source_suffix) if source_env else None
+
+        if promoted_tag:
+            # Todos los cambios que el entorno anterior trae al destino
+            commits = Git.get_commits(merge_commit + "^1", branch, first_parent=False)
+        else:
+            # Commits se obtienen del último merge, listando hasta el primer forkpoint
+            fork_point = Git.get_first_fork_point(branch, target)
+            commits = Git.get_commits(fork_point, branch)
+
+        # Último tag se obtiene localmente
+        current_tag = Git.get_current_tag(suffix)
+
+    if promoted_tag:
+        next_tag = promoted_tag.removesuffix(source_suffix) + suffix
+        base.io_info(
+            f"Merge desde {source_env}: se promueve la versión {promoted_tag} a {target}."
+        )
+
+        # Puede existir si el destino ya llegó a esa versión por otro lado (por ejemplo, un release)
+        existing = api.list_tags(suffix) if api else Git("tag", next_tag, list=True).lines()
+
+        if next_tag in existing:
+            raise GitFlowError(f"El tag {next_tag} ya existe en {target}.")
+    else:
+        next_tag = get_next_tag_from_commits(
+            [c.subject for c in commits], suffix, current_tag
+        )
+
+    if not next_tag:
+        base.io_warning(
+            "Los cambios realizados no implican un salto de versión, se mantiene la anterior."
+        )
+
+        raise typer.Exit(code=1)
+
+    if update_changelog:
+        changelog = Changelog()
+        changelog.update(next_tag, commits)
+        Git("add", Changelog.FILENAME).exec(print="Agregando nuevo CHANGELOG.md")
+        Git("commit", message=Changelog.COMMIT_MESSAGE).exec(print="Creando commit")
+
+        if ci:
+            Git("push").exec()
+
+    tag_commit = Git("show", "HEAD", patch=False, format="%H").firstline()
 
     if ci:
-        Git("push").exec(print="Subiendo commit al remoto para taggearlo")
         base.io_success(base.get_remote_api(token).create_tag(next_tag, tag_commit))
 
     Git("tag", next_tag, tag_commit).exec(print="Creando tag localmente")
 
 
-def get_token_and_ci(token: Optional[str]):
-    try:
-        return (base.ensure_repository_token(), False)
-    except GitFlowError:
+def get_token_and_ci(token: str | None):
+    if token:
         return (token, True)
+    else:
+        return (base.ensure_repository_token(), False)
 
 
-def get_last_merge_commit():
-    commit = Git(
-        "log", first_parent=True, merges=True, max_count=1, format="%h"
-    ).firstline()
-
-    if not commit:
-        raise GitFlowError("No hay merges a taggear.")
-
-    return commit
-
-
-def check_not_tagged(commit: str):
-    tag = Git("describe", commit, tags=True, exact_match=True).firstline(check=False)
-
-    if tag:
-        raise GitFlowError("El commit a taggear ya tiene tag: " + tag)
-
-
-def get_next_tag_from_commits(commits: list[str], branch: str) -> str | None:
+def get_next_tag_from_commits(
+    commits: list[str], suffix: str, current_tag: str | None
+) -> str | None:
     increment = SEMVER_SKIP
     for commit in commits:
-        commit_type = commit[: commit.index(":")]
-        increment = max(increment, COMMIT_TYPE_INCREMENT.get(commit_type, SEMVER_SKIP))
+        match = base.COMMIT_SUBJECT_RE.match(commit)
 
-    tag = Git.get_current_tag() or f"v0.0.0-{branch}"
+        if not match:
+            continue
 
-    until_dash = tag.index("-") if "-" in tag else None
-    suffix = tag[until_dash:] if until_dash is not None else ""
-    [major, minor, patch] = map(int, tag[1:until_dash].split("."))
+        commit_type, breaking, _ = match.groups()
+        commit_increment = SEMVER_MAJOR if breaking else COMMIT_TYPE_INCREMENT.get(commit_type)
+        increment = max(increment, commit_increment or SEMVER_SKIP)
+
+    if increment == SEMVER_SKIP:
+        return None
+
+    version = (current_tag or "v0.0.0" + suffix).removeprefix("v").removesuffix(suffix)
+    [major, minor, patch] = map(int, version.split("."))
 
     if increment == SEMVER_MAJOR:
         major += 1
@@ -105,7 +152,5 @@ def get_next_tag_from_commits(commits: list[str], branch: str) -> str | None:
         patch = 0
     elif increment == SEMVER_PATCH:
         patch += 1
-    elif increment == SEMVER_SKIP:
-        suffix = "-r" + Git("rev-list", "HEAD", count=True).firstline()
 
-    return None if increment == SEMVER_SKIP else f"v{major}.{minor}.{patch}{suffix}"
+    return f"v{major}.{minor}.{patch}{suffix}"

src/git_flow/git.py

@@ -1,9 +1,24 @@
 import subprocess
+from dataclasses import dataclass
+
+from rich.markup import escape
+from rich.panel import Panel
+from rich.text import Text
 
 from git_flow import FLOWCONFIG_FILENAME
 from git_flow.io import *
 
 
+@dataclass
+class Commit:
+    """Datos de un commit necesarios para versionar y generar el changelog."""
+
+    sha: str
+    subject: str
+    email: str
+    is_merge: bool = False
+
+
 class Git:
     class Status:
         worktree: str
@@ -11,8 +26,9 @@ class Git:
         file: str
 
         def __init__(self, line: str) -> None:
-            self.worktree = line[0]
-            self.index = line[1]
+            # Formato porcelain "XY <file>": X es el estado en el indice, Y en el worktree
+            self.index = line[0]
+            self.worktree = line[1]
             self.file = line[3:].strip("\n")
 
     command: list[str]
@@ -52,8 +68,30 @@ class Git:
         return list(map(Git.Status, Git("status", porcelain=True).lines(False)))
 
     @staticmethod
-    def get_current_tag():
-        return Git("describe", abbrev="0", tags=True).firstline(check=False, print="Obteniendo tag actual")
+    def get_current_tag(suffix: str = ""):
+        """Último tag SemVer alcanzable desde HEAD, con el sufijo exacto indicado."""
+        return Git(
+            "describe",
+            abbrev="0",
+            tags=True,
+            match="v[0-9]*.[0-9]*.[0-9]*" + suffix,
+            exclude=None if suffix else "*-*",
+        ).firstline(check=False, print="Obteniendo tag actual")
+
+    @staticmethod
+    def get_promoted_tag(merge_commit: str, suffix: str) -> str | None:
+        """Si el merge trae tags con el sufijo indicado que la rama destino no tenía (por ejemplo,
+        un merge de dev a test trae tags *-dev nuevos), devuelve el más alto de ellos."""
+        tags = Git(
+            "tag",
+            "v[0-9]*.[0-9]*.[0-9]*" + suffix,
+            list=True,
+            merged=merge_commit + "^2",
+            no_merged=merge_commit + "^1",
+            sort="-v:refname",
+        ).lines()
+
+        return tags[0] if tags else None
 
     @staticmethod
     def get_first_fork_point(branch: str, env: str):
@@ -65,6 +103,24 @@ class Git:
 
         return Git("show", env_commits[-1] + "^", patch=False, format="%h").firstline()
 
+    @staticmethod
+    def get_commits(base: str, branch: str, first_parent: bool = True) -> list[Commit]:
+        """Commits propios de la rama (sin merges), del más nuevo al más viejo."""
+        lines = Git(
+            "log",
+            base + ".." + branch,
+            first_parent=first_parent or None,
+            merges=False,
+            format="%h%x09%ae%x09%s",
+        ).lines()
+        commits = []
+
+        for line in lines:
+            [sha, email, subject] = line.split("\t", 2)
+            commits.append(Commit(sha, subject, email))
+
+        return commits
+
     @staticmethod
     def _get_references(kind: str):
         prefix = "refs/" + kind
@@ -115,7 +171,7 @@ class Git:
         process = self._get(**kwargs)
         lines = process.stdout.splitlines()
 
-        return lines if not strip else list(map(lambda l: l.strip(), lines))
+        return lines if not strip else [l.strip() for l in lines]
 
     def firstline(self, **kwargs):
         lines = self.lines(**kwargs)
@@ -129,10 +185,13 @@ class Git:
         self._run(**kwargs)
 
     def _get(self, print: str | None = None, check: bool = True):
-        process = subprocess.run(self.command, capture_output=True, text=True)
+        process = subprocess.run(self.command, capture_output=True, text=True, check=False)
 
-        if print is not None:
-            self._print_process(process.stdout, process.stderr, print)
+        # Sin --verbose solo se muestra el paso; si falla, la salida la muestra main()
+        if print is not None and settings.verbose:
+            self._print_process(process, print)
+        elif print is not None:
+            console.print(Text.assemble(("› ", "cyan"), print))
 
         if check:
             process.check_returncode()
@@ -142,7 +201,7 @@ class Git:
     def _run(self, print: str | None = None, check: bool = True):
         return self._get(print, check)
 
-    def _print_process(self, stdout: str, stderr: str, title: str):
+    def _print_process(self, process: subprocess.CompletedProcess, title: str | None):
         command = []
 
         for arg in self.command:
@@ -154,12 +213,25 @@ class Git:
 
             command.append(arg)
 
-        text = f"[green]$ {' '.join(command)}[/green]"
+        ok = process.returncode == 0
+        # git escribe mensajes informativos en stderr, así que solo se resalta si falló
+        stderr_style = "dim" if ok else "red"
+        text = Text.assemble(("$ ", "dim"), (" ".join(command), "bold yellow"))
 
-        for line in stdout.splitlines():
-            text += "\n" + line
+        for line in process.stdout.splitlines():
+            text.append("\n" + line)
 
-        for line in stderr.splitlines():
-            text += "\n[red]" + line + "[/red]"
+        for line in process.stderr.splitlines():
+            text.append("\n" + line, stderr_style)
 
-        panel(title or "Ejecutando", text)
+        console.print(
+            Panel(
+                text,
+                title=f"[bold]{escape(title or 'Ejecutando')}[/bold]",
+                title_align="left",
+                subtitle=None if ok else f"código de salida {process.returncode}",
+                subtitle_align="right",
+                border_style="bright_black" if ok else "red",
+                expand=False,
+            )
+        )

src/git_flow/io.py

@@ -1,10 +1,19 @@
 from rich.console import Console
-from rich.prompt import Prompt, Confirm
 from rich.panel import Panel
+from rich.prompt import Confirm, Prompt
 
 console = Console(highlight=False)
 
 
+class Settings:
+    """Opciones globales de ejecución, configuradas desde la línea de comandos."""
+
+    verbose: bool = False
+
+
+settings = Settings()
+
+
 def success(msg: str):
     console.print(f":white_check_mark: [green]{msg}[/green]")
 

src/git_flow/main.py

@@ -1,10 +1,15 @@
 #!/usr/bin/env python3
 
+from subprocess import CalledProcessError, SubprocessError
+from typing import Annotated
+
 import typer
+from rich.markup import escape
+from rich.traceback import Traceback
 
 from git_flow import GitFlowError
-import git_flow.command.base as base
-from git_flow.command import init, new, commit, merge, tag, release, branch
+from git_flow.command import base, branch, commit, init, merge, new, release, tag
+from git_flow.io import console, settings
 
 REPOSITORY_TOKEN_PATH = ".repository-token"
 LOCALE = "es_AR.UTF-8"
@@ -20,13 +25,55 @@ app.add_typer(release.app)
 app.add_typer(branch.app)
 
 
+@app.callback()
+def options(
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Muestra la salida de los comandos git y el traceback de los errores",
+        ),
+    ] = False,
+):
+    settings.verbose = verbose
+
+
 def main():
     try:
         app()
         print()
     except GitFlowError as e:
-        base.io_error(str(e), title="Git Flow")
-    except Exception as e:
-        base.io_error(str(e), title="Inesperado")
-    except KeyboardInterrupt as e:
+        _print_error(escape(str(e)), "Git Flow", e)
+    except CalledProcessError as e:
+        _print_error(_format_process_error(e), "Comando", e)
+    except SubprocessError as e:
+        _print_error(escape(str(e)), "Comando", e)
+    except KeyboardInterrupt:
         base.io_error("Ejecución abortada")
+
+
+def _format_process_error(e: CalledProcessError) -> str:
+    command = " ".join(e.cmd) if isinstance(e.cmd, list) else str(e.cmd)
+    message = f"[bold]$ {escape(command)}[/bold]\nTerminó con código de salida {e.returncode}"
+
+    for output in (e.stdout, e.stderr):
+        if isinstance(output, str) and output.strip():
+            message += "\n\n" + escape(output.strip())
+
+    return message
+
+
+def _print_error(message: str, title: str, e: BaseException):
+    if settings.verbose:
+        base.io_error(message, title=title)
+        console.print(
+            Traceback.from_exception(
+                type(e), e, e.__traceback__, suppress=[typer]
+            )
+        )
+    else:
+        base.io_error(
+            message + "\n\n[dim]Ejecutar con `git-flow --verbose <comando>` para ver el detalle[/dim]",
+            title=title,
+        )

src/git_flow/remote/base.py

@@ -1,9 +1,12 @@
 from abc import ABC, abstractmethod
 
+import re
+
 import giturlparse
+import requests
 
 from git_flow import SUPPORTED_REMOTE_URL_SCHEMAS, GitFlowError
-from git_flow.git import Git
+from git_flow.git import Commit, Git
 
 
 class RemoteAPI(ABC):
@@ -65,6 +68,23 @@ class RemoteAPI(ABC):
     def create_tag(self, tag: str, commit: str) -> str:
         pass
 
+    @abstractmethod
+    def get_merge_commits(self, merge_commit: str) -> list[Commit]:
+        """Busca el PR que generó el merge commit y devuelve sus commits (del más nuevo al más
+        viejo), sin depender del historial local."""
+        pass
+
+    @abstractmethod
+    def get_merge_source_branch(self, merge_commit: str) -> str:
+        """Nombre de la rama origen del PR que generó el merge commit."""
+        pass
+
+    @abstractmethod
+    def list_tags(self, suffix: str = "") -> list[str]:
+        """Nombres de los tags del repositorio, sin orden garantizado. `suffix` es solo una pista
+        para que la API filtre; el filtrado definitivo se hace en `get_latest_tag`."""
+        pass
+
     @abstractmethod
     def get_endpoint(self, resource: str) -> str:
         pass
@@ -75,3 +95,45 @@ class RemoteAPI(ABC):
             "Content-Type": "application/json",
             "Authorization": "Bearer " + self.token,
         }
+
+    def get_json(self, url: str, params: dict | None = None):
+        response = requests.get(url, headers=self.get_headers(), params=params)
+
+        if not response.ok:
+            raise GitFlowError(f"Ocurrió un error al consultar {url}: {response.text}")
+
+        return response
+
+    def get_latest_tag(self, suffix: str = "") -> str | None:
+        """Tag SemVer más alto (vX.Y.Z + suffix exacto), o None si no hay ninguno."""
+        pattern = re.compile(rf"^v(\d+)\.(\d+)\.(\d+){re.escape(suffix)}$")
+        versions = {}
+
+        for name in self.list_tags(suffix):
+            match = pattern.match(name)
+
+            if match:
+                versions[tuple(map(int, match.groups()))] = name
+
+        return versions[max(versions)] if versions else None
+
+    def get_all_pages(
+        self,
+        url: str,
+        page_size: int = 50,
+        params: dict | None = None,
+        size_param: str = "per_page",
+    ) -> list:
+        """Recorre un endpoint paginado por número de página (page / per_page)."""
+        items: list = []
+        page = 1
+
+        while True:
+            query = {**(params or {}), "page": page, size_param: page_size}
+            batch = self.get_json(url, query).json()
+            items += batch
+
+            if len(batch) < page_size:
+                return items
+
+            page += 1

src/git_flow/remote/bitbucket.py

@@ -1,5 +1,8 @@
+import re
+
 import requests
 from git_flow import GitFlowError
+from git_flow.git import Commit
 from git_flow.remote.base import RemoteAPI
 
 
@@ -44,5 +47,58 @@ class BitbucketRemoteAPI(RemoteAPI):
         else:
             raise GitFlowError("Ocurrió un error al crear el tag: " + response.text)
 
+    def get_merge_commits(self, merge_commit: str) -> list[Commit]:
+        pr = self._get_merge_pull_request(merge_commit)
+        commits: list[Commit] = []
+        url: str | None = self.get_endpoint(f"pullrequests/{pr['id']}/commits")
+
+        # Bitbucket pagina siguiendo el link "next", y devuelve del más nuevo al más viejo
+        while url:
+            page = self.get_json(url).json()
+
+            for c in page["values"]:
+                raw = c["author"].get("raw", "")
+                match = re.search(r"<(.+?)>", raw)
+                commits.append(
+                    Commit(
+                        c["hash"][:7],
+                        c["message"].splitlines()[0],
+                        match.group(1) if match else raw,
+                        len(c["parents"]) > 1,
+                    )
+                )
+
+            url = page.get("next")
+
+        return commits
+
+    def get_merge_source_branch(self, merge_commit: str) -> str:
+        return self._get_merge_pull_request(merge_commit)["source"]["branch"]["name"]
+
+    def _get_merge_pull_request(self, merge_commit: str) -> dict:
+        prs = self.get_json(self.get_endpoint(f"commit/{merge_commit}/pullrequests")).json()
+        pr = next((p for p in prs["values"] if p["state"] == "MERGED"), None)
+
+        if not pr:
+            raise GitFlowError(f"No se encontró un PR para el commit {merge_commit}")
+
+        return pr
+
+    def list_tags(self, suffix: str = "") -> list[str]:
+        names: list[str] = []
+        url: str | None = self.get_endpoint("refs/tags")
+        params: dict[str, int|str] | None = {"pagelen": 100}
+
+        if suffix:
+            params["q"] = f'name ~ "{suffix}"'
+
+        while url:
+            page = self.get_json(url, params).json()
+            names += [t["name"] for t in page["values"]]
+            url = page.get("next")
+            params = None  # "next" ya incluye la query
+
+        return names
+
     def get_endpoint(self, resource: str) -> str:
         return f"{BitbucketRemoteAPI.API_ENDPOINT}/{self.repository}/{resource}"

src/git_flow/remote/gitea.py

@@ -1,5 +1,6 @@
 import requests
 from git_flow import GitFlowError
+from git_flow.git import Commit
 from git_flow.remote.base import RemoteAPI
 
 
@@ -44,6 +45,46 @@ class GiteaRemoteAPI(RemoteAPI):
         else:
             raise GitFlowError("Ocurrió un error al crear el tag: " + response.text)
 
+    def get_merge_commits(self, merge_commit: str) -> list[Commit]:
+        pr = self._get_merge_pull_request(merge_commit)
+        url = self.get_endpoint(f"/pulls/{pr['number']}/commits")
+        items: list = []
+        page = 1
+
+        # Gitea pagina con page / limit
+        while True:
+            batch = self.get_json(
+                url, {"page": page, "limit": 50, "files": "false", "verification": "false"}
+            ).json()
+            items += batch
+
+            if len(batch) < 50:
+                break
+
+            page += 1
+
+        # La API los devuelve del más viejo al más nuevo
+        return [
+            Commit(
+                c["sha"][:7],
+                c["commit"]["message"].splitlines()[0],
+                c["commit"]["author"]["email"],
+                len(c["parents"]) > 1,
+            )
+            for c in reversed(items)
+        ]
+
+    def get_merge_source_branch(self, merge_commit: str) -> str:
+        return self._get_merge_pull_request(merge_commit)["head"]["ref"]
+
+    def _get_merge_pull_request(self, merge_commit: str) -> dict:
+        return self.get_json(self.get_endpoint(f"/commits/{merge_commit}/pull")).json()
+
+    def list_tags(self, suffix: str = "") -> list[str]:
+        tags = self.get_all_pages(self.get_endpoint("/tags"), 50, size_param="limit")
+
+        return [t["name"] for t in tags]
+
     def get_endpoint(self, resource: str) -> str:
         return f"{self.base_url}/api/v1/repos/{self.repository}{resource}"
     

src/git_flow/remote/github.py

@@ -1,5 +1,6 @@
 import requests
 from git_flow import GitFlowError
+from git_flow.git import Commit
 from git_flow.remote.base import RemoteAPI
 
 
@@ -42,5 +43,35 @@ class GithubRemoteAPI(RemoteAPI):
         else:
             raise GitFlowError("Ocurrió un error al crear el tag: " + response.text)
 
+    def get_merge_commits(self, merge_commit: str) -> list[Commit]:
+        pr = self._get_merge_pull_request(merge_commit)
+        items = self.get_all_pages(self.get_endpoint(f"/pulls/{pr['number']}/commits"), 100)
+
+        # La API los devuelve del más viejo al más nuevo
+        return [
+            Commit(
+                c["sha"][:7],
+                c["commit"]["message"].splitlines()[0],
+                c["commit"]["author"]["email"],
+                len(c["parents"]) > 1,
+            )
+            for c in reversed(items)
+        ]
+
+    def get_merge_source_branch(self, merge_commit: str) -> str:
+        return self._get_merge_pull_request(merge_commit)["head"]["ref"]
+
+    def _get_merge_pull_request(self, merge_commit: str) -> dict:
+        prs = self.get_json(self.get_endpoint(f"/commits/{merge_commit}/pulls")).json()
+        pr = next((p for p in prs if p.get("merge_commit_sha") == merge_commit), None)
+
+        if not pr:
+            raise GitFlowError(f"No se encontró un PR para el commit {merge_commit}")
+
+        return pr
+
+    def list_tags(self, suffix: str = "") -> list[str]:
+        return [t["name"] for t in self.get_all_pages(self.get_endpoint("/tags"), 100)]
+
     def get_endpoint(self, resource: str) -> str:
         return f"{GithubRemoteAPI.API_ENDPOINT}/{self.repository}{resource}"

src/git_flow/remote/gitlab.py

@@ -2,6 +2,7 @@ from urllib.parse import quote
 
 import requests
 from git_flow import GitFlowError
+from git_flow.git import Commit
 from git_flow.remote.base import RemoteAPI
 
 
@@ -47,6 +48,42 @@ class GitlabRemoteAPI(RemoteAPI):
         else:
             raise GitFlowError("Ocurrió un error al crear el tag: " + response.text)
 
+    def get_merge_commits(self, merge_commit: str) -> list[Commit]:
+        mr = self._get_merge_request(merge_commit)
+        items = self.get_all_pages(self.get_endpoint(f"/merge_requests/{mr['iid']}/commits"), 100)
+
+        # GitLab ya los devuelve del más nuevo al más viejo
+        return [
+            Commit(
+                c["short_id"][:7],
+                c["title"],
+                c["author_email"],
+                len(c["parent_ids"]) > 1,
+            )
+            for c in items
+        ]
+
+    def get_merge_source_branch(self, merge_commit: str) -> str:
+        return self._get_merge_request(merge_commit)["source_branch"]
+
+    def _get_merge_request(self, merge_commit: str) -> dict:
+        mrs = self.get_json(
+            self.get_endpoint(f"/repository/commits/{merge_commit}/merge_requests")
+        ).json()
+        mr = next((m for m in mrs if m.get("merge_commit_sha") == merge_commit), None)
+
+        if not mr:
+            raise GitFlowError(f"No se encontró un MR para el commit {merge_commit}")
+
+        return mr
+
+    def list_tags(self, suffix: str = "") -> list[str]:
+        # "search" soporta "$" para anclar al final del nombre
+        params = {"search": suffix + "$"} if suffix else None
+        tags = self.get_all_pages(self.get_endpoint("/repository/tags"), 100, params)
+
+        return [t["name"] for t in tags]
+
     def get_endpoint(self, resource: str) -> str:
         project_id = quote(self.repository, safe="")
         return f"{self.base_url}/api/v4/projects/{project_id}{resource}"