# Marcar versiones

URL canónica: https://missyera.com/guias/git-desde-cero/marcar-versiones/
Última actualización: 2026-11-17
Autora: Gera Flores (Miss Yera)

> **Respuesta corta**
>
> <strong>Una etiqueta es un nombre fijo para un commit.</strong> Se pone con <code>git tag -a v1.0 -m "..."</code> y se sube aparte, porque <code>git push</code> a secas no las lleva. Sirve para poder decir "el reporte de octubre salió con la v1.2" y volver a ese punto exacto cuando haga falta. Y la regla que no se rompe: una etiqueta ya publicada no se mueve nunca.

Capítulo 24 de 33 del libro [Git desde cero](https://missyera.com/guias/git-desde-cero.md).

Un hash como `54da6e2` identifica un momento perfectamente, pero no se puede decir por teléfono. Las etiquetas son eso: ponerle a un commit un nombre que un humano pueda repetir 🏷️

## Qué número poner

La costumbre más extendida son tres números, `1.4.2`, y cada uno dice algo:

| Número | Se sube cuando | Ejemplo |
|---|---|---|
| El primero | Algo cambia y rompe lo anterior | El reporte ya no acepta el CSV viejo |
| El segundo | Hay algo nuevo que no rompe nada | Se agrega el corte por canal |
| El tercero | Solo se arregló un error | Se corrige el total de Arequipa |

No hay policía de versiones: si tu proyecto es tuyo, numera como quieras. Pero si otra gente lo usa, esta convención les dice de un vistazo si actualizar es seguro 🚦

## Poner la primera

```bash
mkdir reporte-ventas
cd reporte-ventas
git init -q
printf 'ciudad,monto\nLima,1200\nArequipa,890\n' > ventas.csv
git add ventas.csv
git commit -q -m "Primeras ventas de Lima y Arequipa"
git tag -a v1.0 -m "Primera version del reporte por ciudad"
git tag
git log --oneline --decorate -1
```

```text
v1.0
2a3fc36 (HEAD -> main, tag: v1.0) Primeras ventas de Lima y Arequipa
```

Ese `-a` hace la etiqueta **anotada**, que guarda quién la puso, cuándo y por qué. Sin él sale una etiqueta ligera, que es solo un apodo. Para versiones que se publican, siempre anotada 📌

```bash
git show v1.0 --stat
```

```text
tag v1.0
Tagger: Miss Yera <hola@missyera.com>
Date:   Thu Jan 15 09:00:00 2026 -0500

Primera version del reporte por ciudad

commit 2a3fc36beb5c2a9e53847d7ea23f4af29abc0159
Author: Miss Yera <hola@missyera.com>
Date:   Thu Jan 15 09:00:00 2026 -0500

    Primeras ventas de Lima y Arequipa

 ventas.csv | 3 +++
 1 file changed, 3 insertions(+)
```

## Seguir trabajando y marcar otra

```bash
printf 'canal,monto\nBodegas,4200\n' > canales.csv
git add canales.csv
git commit -q -m "Se agrega el corte por canal"
git tag -a v1.1 -m "Entra el corte por canal"
printf 'Horeca,3100\n' >> canales.csv
git add canales.csv
git commit -q -m "Entra el canal horeca"
git tag
git log --oneline --decorate
```

```text
v1.0
v1.1
98967f2 (HEAD -> main) Entra el canal horeca
f1d698c (tag: v1.1) Se agrega el corte por canal
2a3fc36 (tag: v1.0) Primeras ventas de Lima y Arequipa
```

Las etiquetas se quedan pegadas a su commit aunque la historia siga creciendo. Por eso sirven 📍

## Dónde estoy respecto a la última versión

```bash
git describe --tags
```

```text
v1.1-1-g98967f2
```

Léelo así: estás en la `v1.1`, más un commit, y el hash del que estás. Es lo que se pone en un pie de página o en un `--version` para saber exactamente qué está corriendo 🧭

## Volver a una versión para mirarla

```bash
git switch -q --detach v1.0
ls
cat ventas.csv
git switch -q -
ls
```

```text
ventas.csv
ciudad,monto
Lima,1200
Arequipa,890
canales.csv
ventas.csv
```

En `v1.0` todavía no existía `canales.csv`. Miraste el pasado y volviste, sin tocar nada 🕰️

## Subirlas, que es el paso que se olvida

`git push` a secas **no lleva las etiquetas**. Hay que pedirlo:

```bash
cd ..
git init -q --bare servidor.git
cd reporte-ventas
git remote add origin ../servidor.git
git push -q -u origin main
git ls-remote --tags origin
echo "(vacio: el push no se llevo las etiquetas)"
git push -q origin --tags
git ls-remote --tags origin
```

```text
(vacio: el push no se llevo las etiquetas)
338723d51e19edad2924403c1b845d25495ef487	refs/tags/v1.0
2a3fc36beb5c2a9e53847d7ea23f4af29abc0159	refs/tags/v1.0^{}
7612cccf58b10b4b71b6fcf891980fc26dca89aa	refs/tags/v1.1
f1d698c97156556250655f4ab4f20d30c03c1d10	refs/tags/v1.1^{}
```

Ahí están. Es el olvido más común del capítulo: la versión marcada en tu máquina y nadie más la ve 🙈

## Qué es un release entonces

Un release es de GitHub, no de Git: es una etiqueta **más** una página con notas de la versión y archivos para descargar. Se crea desde *Releases > Draft a new release* eligiendo una etiqueta que ya exista.

O sea que el orden es: etiqueta primero, release después. Y lo que hace valioso a un release son las notas: qué cambió, qué se rompe y qué hay que hacer para actualizar 📝

La trampa

Marcas la versión 1.0 del reporte, la anuncias, y descubres un error de dedo. Lo arreglas y mueves la etiqueta al commit nuevo.

```
$ git tag -f v1.0
Updated tag 'v1.0' (was 3c1f80a)
$ git push -f origin v1.0

# y en la maquina de tu compañera, que ya la tenia:
$ git describe --tags
v1.0        # pero apuntando a otro commit
```

**Qué está mal**

Ahora hay dos versiones 1.0 distintas en el mundo 😵

Una etiqueta es una promesa: "v1.0 es exactamente este contenido". Quien ya se la bajó no la vuelve a traer, porque Git supone que una etiqueta no cambia. O sea que su v1.0 y la tuya son cosas distintas con el mismo nombre.

Cuando eso pasa, depurar es imposible: dos personas ejecutan "la misma versión" y obtienen resultados diferentes.

La regla: **una etiqueta publicada no se mueve**. Si salió con un error, se saca una v1.0.1 y se sigue hacia adelante. Sale más barato que explicarle a cada uno cuál v1.0 tiene.

## Comprueba que se entendió

Comprueba que lo tienes

Publicaste la v1.0 y descubres un error. ¿Qué haces?

- Muevo la etiqueta v1.0 al commit arreglado
- Saco una v1.0.1 con el arreglo
- Borro la v1.0 y la vuelvo a crear
- Aviso por el chat de que la v1.0 cambió

## Ejercicios

**1. Marca la primera versión**

Crea el proyecto del catálogo y ponle una etiqueta anotada.

```bash
cd ..
mkdir catalogo
cd catalogo
git init -q
printf 'bodega,ciudad\nBodega Inti,Cusco\n' > bodegas.csv
git add bodegas.csv
git commit -q -m "Catalogo inicial de bodegas"
git tag -a v1.0 -m "Primera version del catalogo"
git tag
git log --oneline --decorate -1
```

```text
v1.0
a9874ae (HEAD -> main, tag: v1.0) Catalogo inicial de bodegas
```

La etiqueta aparece al lado del hash.

**2. Mira qué guarda la etiqueta**

Una etiqueta anotada guarda autor, fecha y mensaje.

```bash
git show v1.0 --stat
```

```text
tag v1.0
Tagger: Miss Yera <hola@missyera.com>
Date:   Thu Jan 15 09:00:00 2026 -0500

Primera version del catalogo

commit a9874ae5ade9ebff480ec9f29629b1b651573849
Author: Miss Yera <hola@missyera.com>
Date:   Thu Jan 15 09:00:00 2026 -0500

    Catalogo inicial de bodegas

 bodegas.csv | 2 ++
 1 file changed, 2 insertions(+)
```

Todo eso es lo que no tendrías con una etiqueta ligera.

**3. Avanza y marca la siguiente**

Agrega los minimarkets y saca la v1.1.

```bash
printf 'Minimarket Sol,Trujillo\n' >> bodegas.csv
git add bodegas.csv
git commit -q -m "Entra el minimarket de Trujillo"
git tag -a v1.1 -m "Entran los minimarkets"
git tag
git log --oneline --decorate
```

```text
v1.0
v1.1
4cb519a (HEAD -> main, tag: v1.1) Entra el minimarket de Trujillo
a9874ae (tag: v1.0) Catalogo inicial de bodegas
```

Dos versiones marcadas y cada una en su commit.

**4. Averigua dónde estás**

Un commit después de la última versión.

```bash
printf 'Mayorista Norte,Piura\n' >> bodegas.csv
git add bodegas.csv
git commit -q -m "Entra el mayorista de Piura"
git describe --tags
```

```text
v1.1-1-gb9f725d
```

La versión, cuántos commits llevas encima y el hash 🧭

**5. Vuelve a mirar la v1.0**

Ve al pasado y regresa.

```bash
git switch -q --detach v1.0
cat bodegas.csv
git switch -q -
cat bodegas.csv
```

```text
bodega,ciudad
Bodega Inti,Cusco
bodega,ciudad
Bodega Inti,Cusco
Minimarket Sol,Trujillo
Mayorista Norte,Piura
```

Una sola bodega en la v1.0, tres al volver. Ese es el valor de marcar 🕰️

**6. Súbelas al servidor**

Comprueba que el push normal no las lleva y mándalas aparte.

```bash
cd ..
git init -q --bare catalogo-servidor.git
cd catalogo
git remote add origin ../catalogo-servidor.git
git push -q -u origin main
git ls-remote --tags origin
echo "(vacio)"
git push -q origin --tags
git ls-remote --tags origin
```

```text
(vacio)
419ab5b7a0a3013255e90441edc5eaa0cff0c009	refs/tags/v1.0
a9874ae5ade9ebff480ec9f29629b1b651573849	refs/tags/v1.0^{}
5a7e66660e45be3d87f34c46a36b17047428c670	refs/tags/v1.1
4cb519af668b35459949b56f5823d8dc0c4b868a	refs/tags/v1.1^{}
```

Antes nada, después las dos. Es el paso que más se olvida 🙈

**7. Intenta crear una etiqueta que ya existe**

Prueba a poner otra vez la v1.0.

```bash
git tag -a v1.0 -m "Otra vez la primera"
```

```
fatal: tag 'v1.0' already exists
```

Git no deja pisar una etiqueta sin que se lo pidas a propósito, y esa negativa es justo la que protege a quien ya se la bajó 🛡️

## Lo que te llevas

**Una etiqueta anotada por versión, se sube con `--tags`, y una vez publicada no se mueve.**

## Seguir leyendo

- Anterior: [Revisar el trabajo de otra persona](https://missyera.com/guias/git-desde-cero/revisar-el-trabajo-ajeno.md)
- Siguiente: [Recuperar lo que creías perdido](https://missyera.com/guias/git-desde-cero/recuperar-lo-perdido.md)

## Contacto

- Diagnóstico de 30 minutos con Miss Yera: https://calendly.com/soymissyera/reunion-con-yera
- Correo: hola@missyera.com
- Esta página en HTML: https://missyera.com/guias/git-desde-cero/marcar-versiones/
- Índice de todas las páginas en texto: https://missyera.com/llms-index.txt
