Merge pull request 'feature: when merging environments, promote tag from previous env to next env' (#62) from feature/promote-tag-when-merging-environments into main

Reviewed-on: #62

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

@@ -13,37 +13,21 @@ jobs:
         with:
           fetch-depth: 10
 
-      - 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: Install git-flow and bump version
         id: version
         run: |
           pip install git-flow-envs=="${{ vars.GITFLOWENVS_VERSION }}"
           git-flow tag --token="${{ secrets.GITEA_TOKEN }}"
-          RESULT="$?"
 
-          if [ "$RESULT" -eq 0 ]; then
+      - name: Install uv
-            echo "New tag available."
+        uses: astral-sh/setup-uv@v8.3.2
-            echo "should_build=true" >> $GITHUB_OUTPUT
-          else
-            echo "No new tag available, skipping next step."
-            echo "should_build=false" >> $GITHUB_OUTPUT
-          fi
 
       - name: Build and publish
-        if: steps.version.outputs.should_build == 'true'
         run: |
           uv build
           uv publish --token="${{ secrets.PYPI_TOKEN }}"

README.md

@@ -67,9 +67,12 @@ más información):
 - `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.
+- `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.
 
 El workflow para el cual se penso la herramienta es el siguiente:
 
@@ -88,9 +91,35 @@ 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.
+- 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

branch-clean-report.csv

@@ -0,0 +1,2 @@
+name,commit sha,author,date
+worktree-kind-watching-hearth,e8c0c0b777d31fa94cd3f01fbf9c68b165d77015,Jonathan Teran Carballo,2026-09-13T23:18:47-03:00

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/tag.py

@@ -16,20 +16,15 @@ app = typer.Typer()
 
 
 @app.command()
-def tag(token: str | None = None, update_changelog: bool = False):
+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.")
 
-    token, ci = get_token_and_ci(token)
-
-    if ci and not token:
-        raise GitFlowError("No hay token disponible")
-
     merge_commit = Git(
         "log", first_parent=True, merges=True, max_count=1, format="%H"
     ).firstline()
@@ -37,23 +32,62 @@ def tag(token: str | None = None, update_changelog: bool = False):
     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 ci and not token:
+        raise GitFlowError("No hay token disponible")
+
     # 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 ""
 
-    if ci:
+    # 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 = base.get_remote_api(token).get_merge_commits(merge_commit)
+        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 = base.get_remote_api(token).get_latest_tag(suffix)
+        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
-        branch = Git("show", merge_commit + "^2", patch=False, format="%H").firstline()
             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
         )

src/git_flow/git.py

@@ -73,6 +73,21 @@ class Git:
             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):
         # Lista de commits alcanzables por el entorno (por ejemplo, dev),
@@ -84,10 +99,14 @@ class Git:
         return Git("show", env_commits[-1] + "^", patch=False, format="%h").firstline()
 
     @staticmethod
-    def get_commits(base: str, branch: str) -> list[Commit]:
+    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=True, merges=False, format="%h%x09%ae%x09%s"
+            "log",
+            base + ".." + branch,
+            first_parent=first_parent or None,
+            merges=False,
+            format="%h%x09%ae%x09%s",
         ).lines()
         commits = []
 

src/git_flow/remote/base.py

@@ -74,6 +74,11 @@ class RemoteAPI(ABC):
         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

src/git_flow/remote/bitbucket.py

@@ -48,12 +48,7 @@ class BitbucketRemoteAPI(RemoteAPI):
             raise GitFlowError("Ocurrió un error al crear el tag: " + response.text)
 
     def get_merge_commits(self, merge_commit: str) -> list[Commit]:
-        prs = self.get_json(self.get_endpoint(f"commit/{merge_commit}/pullrequests")).json()
+        pr = self._get_merge_pull_request(merge_commit)
-        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}")
-
         commits: list[Commit] = []
         url: str | None = self.get_endpoint(f"pullrequests/{pr['id']}/commits")
 
@@ -77,6 +72,18 @@ class BitbucketRemoteAPI(RemoteAPI):
 
         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")

src/git_flow/remote/gitea.py

@@ -46,7 +46,7 @@ class GiteaRemoteAPI(RemoteAPI):
             raise GitFlowError("Ocurrió un error al crear el tag: " + response.text)
 
     def get_merge_commits(self, merge_commit: str) -> list[Commit]:
-        pr = self.get_json(self.get_endpoint(f"/commits/{merge_commit}/pull")).json()
+        pr = self._get_merge_pull_request(merge_commit)
         url = self.get_endpoint(f"/pulls/{pr['number']}/commits")
         items: list = []
         page = 1
@@ -74,6 +74,12 @@ class GiteaRemoteAPI(RemoteAPI):
             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")
 

src/git_flow/remote/github.py

@@ -44,12 +44,7 @@ class GithubRemoteAPI(RemoteAPI):
             raise GitFlowError("Ocurrió un error al crear el tag: " + response.text)
 
     def get_merge_commits(self, merge_commit: str) -> list[Commit]:
-        prs = self.get_json(self.get_endpoint(f"/commits/{merge_commit}/pulls")).json()
+        pr = self._get_merge_pull_request(merge_commit)
-        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}")
-
         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
@@ -63,6 +58,18 @@ class GithubRemoteAPI(RemoteAPI):
             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)]
 

src/git_flow/remote/gitlab.py

@@ -46,17 +46,10 @@ class GitlabRemoteAPI(RemoteAPI):
         if response.ok:
             return "Tag creado exitosamente: " + tag
         else:
-            raise GitFlowError("Ocurrió un error al crear el tag para repositorio " + quote(self.repository, safe="") + ": " + response.text)
+            raise GitFlowError("Ocurrió un error al crear el tag: " + response.text)
 
     def get_merge_commits(self, merge_commit: str) -> list[Commit]:
-        mrs = self.get_json(
+        mr = self._get_merge_request(merge_commit)
-            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}")
-
         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
@@ -70,6 +63,20 @@ class GitlabRemoteAPI(RemoteAPI):
             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