Uso de Git en GitHub Docs

En este artículo se describe el proceso de creación de una rama puntual para el repositorio de documentación, confirmación de cambios y envío de tu copia de seguridad de cambios al repositorio remoto.

En el artículo se da por supuesto que ya ha clonado el repositorio de documentación localmente y que harás cambios en el equipo local en lugar de en GitHub o en un codespace. Para más información, consulta Clonar un repositorio.

Configuración de la rama puntual y realización de cambios

Para mantener las ramas locales sincronizadas con sus repositorios remotos y evitar conflictos de combinación, sigue estos pasos mientras trabajas en la documentación.

1. En el terminal, cambia el directorio de trabajo actual a la ubicación donde has clonado el repositorio de documentación. Por ejemplo:

   cd ~/my-cloned-repos/docs
   

2. Cambia a la rama predeterminada: main.

   git checkout main
   

3. Obtén las confirmaciones más recientes del repositorio remoto.

   git pull origin main
   

4. Cambia a una rama puntual o crea una.

   • Para iniciar un nuevo proyecto, crea una nueva rama puntual a partir de main.

     git checkout -b YOUR-TOPIC-BRANCH
     

     Note

     Puedes usar barras diagonales como parte del nombre de la rama, por ejemplo, para incluir el nombre de usuario:

     git checkout -b my-username/new-codespace-policy
     

   • Para trabajar en un proyecto existente, cambia a la rama puntual y combina los cambios de main.

     git checkout YOUR-TOPIC-BRANCH
     git merge main
     

     Si tienes conflictos de combinación, sigue los pasos que se describen más adelante en este artículo para resolver conflictos de combinación.

5. Abre tu editor de texto preferido, edita los archivos según sea necesario y guarda los cambios.

Confirmar y subir tus cambios

1. Cuando estés listo para confirmar los cambios, abre un terminal y comprueba el estado de la rama puntual con git status. Asegúrate de que se muestra el conjunto de cambios correcto.

   git status
   On branch YOUR-TOPIC-BRANCH
   
   Changes not staged for commit:
     (use "git add <file>..." to update what will be committed)
     (use "git checkout -- <file>..." to discard changes in working directory)
           deleted:    example-deleted-file.md
           modified:   example-changed-file.md
   
   Untracked files:
     (use "git add <file>..." to include in what will be committed)
           example-new-file.md
   

2. Agrega al "stage" los archivos cambiados de modo que estén listos para confirmarse en la rama puntual.

   • Si has creado nuevos archivos o has actualizado los archivos existentes, usa git add FILENAME [FILENAME...]. Por ejemplo:

     git add example-new-file.md example-changed-file.md
     

     De esta forma se agrega la versión actualizada de los archivos al área de almacenamiento provisional de Git, desde donde se pueden confirmar los cambios. Para sacar del "stage" un archivo, usa git reset HEAD FILENAME. Por ejemplo, git reset HEAD example-changed-file.md.

   • Si has eliminado archivos, usa git rm FILENAME [FILENAME...]. Por ejemplo:

     git rm example-deleted-file.md
     

3. Confirme los cambios.

   git commit -m "Commit message title (max 72 characters)
   
   Optional fuller description of what changed (no character limit).
   Note the empty line between the title and the description,
   and the closing quotation mark at the end of the commit message."
   

   De esta forma se confirman los cambios "staged" localmente. Ahora puedes insertar esta confirmación y cualquier otra confirmación no insertada en el repositorio remoto.

   Para quitar esta confirmación, usa git reset --soft HEAD~1. Después de ejecutar este comando, nuestros cambios ya no se confirman, pero los archivos modificados permanecen en el área de almacenamiento provisional. Puedes realizar más cambios y, a continuación, add y commit de nuevo.

4. Inserta los cambios al repositorio remoto en GitHub.

   • La primera vez que insertes tu rama, puedes optar por agregar una rama de seguimiento ascendente. Esto te permite usar git pull y git push en esa rama sin argumentos adicionales.

     git push --set-upstream origin YOUR-TOPIC-BRANCH
     

   • Si has insertado esta rama antes y has establecido una rama de seguimiento ascendente, puedes usar:

     git push
     

Procedimientos recomendados de confirmaciones

• Favorece las confirmaciones que contengan grupos de cambios pequeños y centrados por encima de las confirmaciones con grupos de cambios grandes y no centrados, ya que esto te ayudará a escribir mensajes de confirmación que otros usuarios puedan comprender fácilmente. Una excepción es la confirmación inicial de un proyecto o categoría nuevos. Estas confirmaciones son en ocasiones grandes, ya que a menudo presentan las versiones básicas de muchos artículos a la vez para proporcionar un esquema organizativo para el trabajo posterior.

• Si vas a incorporar comentarios o quieres abordar un conjunto de cambios en un usuario o equipo determinados para su revisión, @mention al usuario cuyas sugerencias vas a agregar. Por ejemplo: "Incorporación de comentarios de @octocat" o "Actualización de pasos de configuración de facturación: cc @monalisa para una mayor precisión".

• Si una confirmación soluciona una incidencia, puedes hacer referencia al número de incidencia en la confirmación y aparecerá un vínculo a la confirmación en la escala de tiempo de conversación de la incidencia: "Soluciona n.º 1234: agrega pasos para realizar una copia de seguridad de la máquina virtual antes de la actualización".

  Note

  Por lo general, no cerramos una propuesta a través de una confirmación. Para cerrar una incidencia, abre una PR y agrega "Cierra n.º 1234" a la descripción. La incidencia vinculada se cerrará cuando se combine la PR. Para más información, consulta Vincular una solicitud de cambios a una propuesta.

• Haz que los mensajes de confirmación sean claros, detallados e imperativos. Por ejemplo: "Agrega un artículo conceptual sobre 2FA", no "Agrega información".

• Intenta no dejar cambios pendientes de confirmación en la rama local cuando completes el trabajo del día. Accede a un buen punto de detención y confirma y envía los cambios para que se realice una copia de seguridad del trabajo en el repositorio remoto.

• Solo tienes que llevar a cabo la inserción en GitHub una vez que haya hecho unas pocas confirmaciones. La inserción tras cada confirmación agrega ruido a nuestros canales de operaciones en Slack y hace que se ejecuten compilaciones innecesarias.

Resolución de conflictos de combinación

Cuando intentes combinar dos ramas que contienen diferentes cambios en la misma parte de un archivo, obtendrás un conflicto de combinación. En nuestro flujo de trabajo, esto suele ocurrir al combinar main en una rama puntual local.

Hay dos maneras de controlar los conflictos de combinación:

• Edita el archivo en el editor de texto y elige los cambios que se van a conservar. A continuación, confirma el archivo actualizado en la rama puntual desde la línea de comandos.
• Resolver un conflicto de fusión en GitHub.

Resolución de conflictos de combinación mediante la edición del archivo y la confirmación de los cambios

1. En la línea de comandos, ten en cuenta los archivos que contienen conflictos de combinación.

2. Abre el primero de estos archivos en el editor de texto.

3. En el archivo, busca los marcadores de conflicto de combinación.

    <<<<<<< HEAD
    Here are the changes you've made.
    =====================
    Here are the changes from the main branch.
    >>>>>>> main
   

4. Decide qué cambios se van a conservar y elimina los cambios no deseados y los marcadores de conflicto de combinación. Si tienes que realizar más cambios, puedes hacerlo al mismo tiempo. Por ejemplo, podrías cambiar las cinco líneas que se muestran en el ejemplo de código anterior por una sola línea:

   Here are the changes you want to use.
   

   Si hay varios archivos con conflictos de combinación, repite los pasos anteriores hasta que los resuelvas todos.

   Note

   Debes estar atento al resolver conflictos de fusión mediante combinación. En ocasiones, sencillamente aceptarás tus propios cambios, mientras que otras veces usarás los cambios ascendentes de la rama main y combinarás ambos conjuntos de cambios. Si no estás seguro de cuál es la mejor resolución, ten cuidado si reemplazas los cambios ascendentes, ya que es posible que se hayan realizado por motivos específicos que desconoces.

5. En el terminal, agrega al "stage" el archivo o archivos que acabas de modificar.

   git add changed-file-1.md changed-file-2.md
   

6. Confirma los archivos.

   git commit -m "Resolves merge conflicts"
   

7. Inserte los cambios confirmados en el repositorio remoto en GitHub.

   git push
   

Crear una solicitud de incorporación de cambios

Se recomienda que abras la PR en GitHub pronto. Crea la PR como borrador hasta que estés listo para su revisión. Cada vez que envíes cambios, las confirmaciones se agregarán a la PR.

Para más información, consulta Crear una solicitud de incorporación de cambios.