Git para proyectos BIM: versiones con criterio

Una carpeta llamada revision_final_ahora_si ofrece dos datos: alguien esperaba terminar y el sistema de versiones ya ha empezado a expresar emociones. Si aparece otra llamada revision_final_ahora_si_2, la clasificación tiene además una trama. Git permite conservar los cambios de los archivos sin convertir sus nombres en el diario de nuestras decepciones. Su utilidad empieza cuando puedes responder qué cambió, por qué cambió y cómo consultar lo anterior.

Vamos a guardar dos versiones de una regla sencilla de revisión de puertas. Después recuperaremos el contenido anterior conservando el recorrido de decisiones. Todo ocurrirá en una carpeta de ejercicio independiente, sin cuenta de GitHub y sin enviar archivos a ningún servidor. No necesitas dominar ramas, servidores o estrategias de integración para dejar de sustituir un archivo a ciegas. Empezar por ese problema concreto ahorra bastante mitología alrededor de una herramienta que, bien utilizada, debería reducir incertidumbre.

Un historial útil conserva algo más que el archivo anterior

Nuestra regla será un documento de texto llamado regla.txt. Tendrá tres líneas: nivel objetivo, catálogo admitido y acción de solo lectura. No es un archivo que Revit vaya a interpretar ni un formato de configuración obligatorio para Python. Nos sirve para observar un cambio de criterio sin tener que explicar al mismo tiempo un programa.

				
					nivel_objetivo=L01
catalogo=D01,D02
accion=solo_lectura

Si cambiamos L01 por L02 y guardamos, el editor habrá conservado el contenido nuevo. Por sí solo, ese archivo ya no explica qué había antes ni por qué se eligió otra planta. Podrías hacer una copia, añadir una fecha o escribir un comentario en otro lugar. Git permite registrar una versión y asociarle un mensaje, manteniendo una relación explícita entre los archivos y el cambio.

Ese registro se llama commit. Puedes entenderlo como un punto del historial que identifica una versión del conjunto de archivos guardados por Git. No equivale a pulsar guardar en el editor: tú decides cuándo crear ese punto y qué cambios incluir. Tampoco acredita que la regla esté bien elegida o que se haya probado el programa. Un commit puede conservar con admirable exactitud una decisión equivocada. La herramienta aporta memoria; el criterio sigue teniendo que venir de algún sitio.

Por eso un mensaje como «cambios» desperdicia una parte del mecanismo. Si la revisión pasa a L02 porque el ejercicio se concentra en esa planta, el mensaje debería expresarlo. Al volver semanas después, interesa reconocer la intención sin reconstruirla comparando caracteres. Guardar la diferencia es trabajo de Git. Explicar por qué la diferencia merece existir nos corresponde a nosotros, una distribución de responsabilidades que considero bastante razonable.

Crear el repositorio en un sitio donde podamos equivocarnos

Comprueba que Git está instalado ejecutando git --version. Después crea una carpeta nueva de ejercicio y entra en ella. Los comandos de este artículo se pueden introducir en PowerShell; los archivos de texto puedes guardarlos desde tu editor. No hagas la demostración dentro de un repositorio real que ya tenga cambios de trabajo.

				
					mkdir historial-puertas
cd historial-puertas
git init

git init prepara un repositorio local en esa carpeta. Git conservará su información en un directorio llamado .git. No necesitas editar sus archivos ni copiarlo por partes. A partir de este momento, los comandos ejecutados aquí podrán relacionar los archivos de trabajo con el historial de este repositorio.

Para registrar los commits, Git utiliza un nombre y un correo de autoría. En este ejercicio podemos configurar una identidad ficticia únicamente para el repositorio local:

				
					git config user.name "Ejemplo Codigo BIM"
git config user.email "ejemplo@example.invalid"

No estamos configurando una cuenta de GitHub ni verificando una identidad. Estos valores serán metadatos de los commits de prueba. En un proyecto que compartas tendrás que elegir la identidad que corresponda; aquí no hace falta utilizar datos personales. La ausencia de --global hace que la configuración se aplique al repositorio del ejercicio y no cambie la identidad de los demás trabajos.

Guarda ahora regla.txt con el contenido anterior y un README.md que explique brevemente el alcance: «Revisión ficticia de códigos de puertas; no modifica modelos». El nombre README es una convención para situar a quien abre el proyecto. Es una ayuda bastante más eficaz que obligarle a deducir la finalidad leyendo todos los archivos mientras el autor observa con orgullo.

Elegir qué entra antes de guardar la primera versión

Ejecuta git status. Los archivos nuevos aparecerán como no seguidos: están en la carpeta, pero todavía no forman parte de un commit. Git no incorpora automáticamente cualquier cosa que encuentre. Entre el directorio de trabajo y el commit existe una selección de cambios preparada para guardar, que suele llamarse área de preparación o staging.

Antes de incorporar los archivos, crea otro llamado .gitignore con este contenido:

				
					.venv/
.env
__pycache__/

El entorno virtual se puede reconstruir a partir de las instrucciones y dependencias. El archivo .env, si lo utilizamos, puede contener configuración local o secretos y no queremos añadirlo al ejemplo compartido. __pycache__ recoge archivos generados por Python. Las exclusiones responden a lo que nuestro proyecto necesita; no hemos pegado un catálogo universal de cientos de patrones para parecer más previsores.

Selecciona los archivos que sí describen el ejercicio y revisa la preparación:

				
					git add .gitignore README.md regla.txt
git diff --staged
git commit -m "Define la revision de puertas del nivel L01"

git add prepara el contenido actual de esos archivos. git diff --staged permite inspeccionar lo que se va a guardar. El commit registra esa selección con su mensaje. La explicación oficial del registro de cambios en Git desarrolla esta separación entre archivos de trabajo, preparación e historial.

La distinción importa en cuanto empiezas a corregir algo después de preparar una primera versión. Si editas otra vez un archivo que ya habías añadido, el contenido preparado puede ser distinto del que ahora muestra el editor. No hay una contradicción: son dos estados que Git permite inspeccionar por separado. git diff muestra cambios del trabajo respecto a la preparación; git diff --staged muestra lo preparado respecto al último commit. Saber cuál estás mirando evita confirmar una versión que ya creías corregida.

No usaría git add . como primer reflejo en una carpeta cuyo contenido todavía no conozco. Puede ser perfectamente válido cuando has revisado el conjunto y sus exclusiones. En este ejercicio prefiero nombrar tres archivos: obliga a reconocer qué estamos entregando y reduce la oportunidad de incluir una captura, una exportación o un archivo de configuración que solo pasaba por allí.

La diferencia permite discutir una decisión concreta

Abre regla.txt y cambia únicamente nivel_objetivo=L01 por nivel_objetivo=L02. Guarda y ejecuta:

				
					git diff -- regla.txt

La diferencia debe mostrar la línea anterior y la nueva. Los signos menos y más del diff describen contenido retirado y añadido; no son líneas que debas escribir dentro de la regla. El catálogo y la acción de lectura no deberían aparecer modificados. Si aparece reescrito todo el archivo, revisa si tu editor ha cambiado también codificación o finales de línea antes de concluir que Git se ha puesto dramático.

Este cambio pequeño ofrece una revisión con una pregunta clara: ¿queremos trasladar la selección a L02 manteniendo el resto del criterio? Si en el mismo commit hubiéramos cambiado además el catálogo, renombrado archivos y preparado una escritura en el modelo, la conversación sería mucho menos precisa. Un commit no necesita representar un número fijo de líneas; necesita agrupar una intención que se pueda entender.

Guarda ahora esa segunda decisión:

				
					git add regla.txt
git diff --staged
git commit -m "Traslada la revision al nivel L02"
git log --oneline

El historial debería incluir las dos decisiones, acompañadas de identificadores de commit. Sus valores concretos pueden ser distintos en tu equipo: dependen del contenido y de metadatos del registro, entre otras cosas. No tienes que obtener el mismo código que una captura para demostrar que el ejercicio funciona. Lo verificable es que existan las dos versiones y que sus diferencias sean las previstas.

Todavía no hemos enviado nada a un servidor. Git funciona localmente; GitHub es uno de los servicios con los que puedes compartir repositorios. Hacer un commit y hacer un push son operaciones diferentes. Esta distinción evita tanto creer que un trabajo ya está respaldado fuera del equipo como temer que cualquier prueba local publique automáticamente un archivo. Las dos confusiones tienen seguidores suficientes sin nuestra ayuda.

Consultar lo anterior es más seguro que restaurarlo sin mirar

Antes de modificar el estado actual podemos consultar el contenido de la versión anterior:

				
					git show HEAD~1:regla.txt

En este historial lineal, HEAD señala el commit actual y HEAD~1 su primer antecesor. El comando muestra el archivo de ese punto sin reemplazar el que tienes abierto. Deberías volver a ver L01. Si tu objetivo era únicamente comprobar qué se había acordado antes, ya has terminado: no necesitas cambiar archivos por el placer de utilizar otra orden.

Supongamos ahora que decides volver a L01 y quieres conservar constancia de esa vuelta. Primero utiliza git status y git diff -- regla.txt para asegurarte de que no hay una edición sin guardar en el historial que quieras conservar. Restaurar el archivo puede sobrescribir cambios de trabajo. Hazlo únicamente cuando hayas identificado qué sustituirá y de dónde saldrá el contenido.

				
					git restore --source=HEAD~1 -- regla.txt
git diff -- regla.txt
git add regla.txt
git commit -m "Recupera L01 como alcance de la revision"

La referencia de git restore describe la selección del origen y los archivos afectados. En este caso hemos recuperado un único archivo y creado un commit nuevo para dejar rastro de la decisión. Las versiones intermedias siguen en el historial. No hemos utilizado reset --hard, no hemos reescrito commits y no hemos pedido que desaparezca evidencia de que antes se eligió L02.

El ejercicio termina con tres registros y un directorio de trabajo limpio. Que esté limpio significa que Git no detecta cambios pendientes respecto a sus estados de referencia, no que el contenido haya recibido una aprobación técnica. Para nuestra regla, todavía habría que comprobar los resultados sobre las puertas. El historial ayuda a situar esa prueba; no la realiza por delegación.

Ignorar un archivo no borra lo que ya compartiste

Si creas un .env ficticio después de guardar las exclusiones, git status no debería proponerlo como archivo nuevo. Puedes consultar qué patrón se aplica con git check-ignore -v .env. Eso confirma el comportamiento de esta exclusión, pero no convierte .gitignore en un mecanismo de protección de secretos que ya hayan entrado en el historial.

La documentación de archivos ignorados aclara que los archivos ya seguidos no quedan afectados por esas reglas. Si se confirmó una credencial real, añadir después .env a las exclusiones no la retira de los commits anteriores. Habrá que tratar la exposición de esa credencial y decidir una corrección del historial acorde con cómo se haya compartido. El problema ya no consiste en conseguir que status tenga un aspecto tranquilizador.

Para continuar con nuestros ejercicios, la regla de trabajo puede ser sencilla: guarda los archivos que permiten entender y reproducir el resultado, revisa el diff antes del commit y acompaña cada cambio de una razón reconocible. Cuando aparezca una diferencia en el informe, podrás comparar la regla y los datos que la provocaron. Si lo único que conservas es una carpeta «buena» y la memoria de quien la creó, todavía no tienes un historial. Tienes una persona convertida en dependencia del proyecto, con horarios de atención y una probabilidad razonable de irse de vacaciones.