Búsqueda de sitios web

7 consejos de Git para escritores técnicos


Siga esta demostración de cómo uso Git para escribir documentación para Foreman.

Como redactor técnico que trabaja para ATIX, mis tareas incluyen la creación y el mantenimiento de documentación para Foreman en github.com/theforeman/foreman-documentation. Git me ayuda a rastrear versiones de contenido y a colaborar con la comunidad de código abierto. Es una parte integral de almacenar los resultados de mi trabajo, compartirlos y discutir mejoras. Mis herramientas principales incluyen mi navegador, OpenSSH para conectarme a instancias de Foreman, Vim para editar archivos fuente y Git para versionar el contenido.

Este artículo se centra en los desafíos recurrentes al dar los primeros pasos con Git y contribuir a la documentación de Foreman. Esto está destinado a usuarios intermedios de Git.

Requisitos previos

  • Ha instalado y configurado Git en su sistema. Debe al menos configurar su nombre de usuario y dirección de correo electrónico.

  • Tienes una cuenta en github.com. GitHub no es un proyecto de código abierto en sí mismo, pero es el sitio donde se almacenan muchos repositorios de Git de código abierto (incluida la documentación de Foreman).

  • Ha bifurcado el repositorio de documentación de Foreman en su propia cuenta u organización (por ejemplo, github.com/_My_User_Account_/foreman-documentation. Para obtener más información, consulte Un paso- Guía paso a paso de Git por Kedar Vijay Kulkarni.

  • Ha agregado su clave pública SSH a GitHub. Esto es necesario para enviar sus cambios a GitHub. Para obtener más información, consulte Una breve introducción a GitHub de Nicole C. Baratta.

Contribuir a la documentación de Foreman

Foreman es un proyecto de código abierto y se nutre de las contribuciones de la comunidad. El proyecto da la bienvenida a todos y solo existen unos pocos requisitos para realizar contribuciones significativas. Los requisitos y convenciones están documentados en los archivos README.md y CONTRIBUTING.md.

Estas son algunas de las tareas más frecuentes cuando se trabaja en la documentación de Foreman.

Quiero empezar a trabajar en la documentación de Foreman.

  1. Clona el repositorio de github.com:

    $ git clone git@github.com:theforeman/foreman-documentation.git$ cd foreman-documentation/
  2. Cambie el nombre del control remoto:

    $ git remote rename origin upstream
  3. Opcional: asegúrese de que su sucursal maestra local esté rastreando la sucursal maestra desde el repositorio foreman-documentation de la organización theforeman:

    $ git status

    Esto lo inicia automáticamente en la última confirmación de la rama predeterminada, que en este caso es master.

  4. Si aún no tiene una bifurcación del repositorio en su propia cuenta u organización, cree una.

    Vaya a github.com/theforeman/foreman-documentation y haga clic en Fork.

  5. Agrega tu bifurcación a tu repositorio.

    $ git remote add github git@github.com:_My_User_Account_/foreman-documentation.git

    Su repositorio local ahora tiene dos controles remotos: upstream y github.

Quiero ampliar la documentación de Foreman.

Para cambios simples, como corregir un error ortográfico, puede crear una solicitud de extracción (PR) directamente.

  1. Cree una rama denominada, por ejemplo, fix_spelling. El comando git switch cambia la rama actualmente desprotegida y -c crea la rama:

    $ git switch -c fix_spelling
  2. Haz tu cambio.

  3. Agregue su cambio y confirme:

    $ git add guides/common/modules/abc.adoc$ git commit -m "Fix spelling of existing"

    No puedo enfatizar lo suficiente la importancia de buenos mensajes de confirmación de Git. Un mensaje de confirmación les dice a los contribuyentes lo que ha hecho y, debido a que se conserva junto con el resto del código base, sirve como una nota histórica a pie de página cuando alguien revisa el código para determinar qué sucedió durante su vida útil. Para obtener más información sobre excelentes mensajes de confirmación de Git, consulte Las siete reglas de un excelente mensaje de confirmación de Git de cbeams.

  4. Opcional pero recomendado: vea y verifique la diferencia con la rama predeterminada. La rama predeterminada para foreman-documentation se llama master, pero otros proyectos pueden nombrar la suya de manera diferente (por ejemplo, main, dev o desarrollo.)

    $ git diff master
  5. Empuja tu rama a Github. Esto publica su cambio en su copia del código base.

    $ git push --set-upstream github fix_spelling
  6. Haga clic en el enlace proporcionado por Git en su terminal para crear una solicitud de extracción (PR).

    remote: Create a pull request for 'fix_spelling' on Github by visiting:remote:      https://github.com/_My_User_Account_/foreman-documentation/pull/new/fix_spelling
  7. Agregue una explicación sobre por qué la comunidad debería aceptar su cambio. Esto no es necesario para un PR trivial, como corregir un error ortográfico, pero para cambios importantes es importante.

Quiero cambiar la base de mi rama para que sea maestra.

  1. Asegúrese de que su rama maestra local rastree la rama maestra desde github.com/theforeman/foreman-documentation, no foreman-documentation en su propio espacio de nombres:

    $ git switch master

    Esto debería decir Su rama está actualizada con 'upstream/master', siendo upstream el nombre de su repositorio remoto que apunta a github.com/theforeman/ documentación-capataz. Puedes revisar tus controles remotos ejecutando git remoto -v.

  2. Recupera posibles cambios desde tu control remoto. El comando git fetch descarga la rama rastreada desde su control remoto y la opción --all actualiza todas las ramas simultáneamente. Esto es necesario cuando se trabaja con sucursales adicionales. La opción --prune elimina las referencias a ramas que ya no existen.

    $ git fetch --all --prune
  3. Extraiga posibles cambios de upstream/master a su rama local master. El comando git pull copia las confirmaciones de la rama que estás rastreando en tu rama actual. Esto se utiliza para "actualizar" su rama master local al último estado de la rama master en su control remoto (Github, en este caso).

    $ git pull
  4. Cambie la base de su rama a "maestra".

    $ git switch my_branch$ git rebase -i master

Me he comprometido accidentalmente con el maestro.

  1. Crea una rama para guardar tu trabajo:

    $ git switch -c my_feature
  2. Vuelva a la rama master:

    $ git switch master
  3. Suelte la última confirmación en master:

    $ git reset --soft HEAD~1
  4. Vuelva a la rama my_feature y continúe trabajando:

    $ git switch my_feature

Quiero reformular mi mensaje de confirmación

  1. Si solo tienes una confirmación en tu rama, usa git amend para cambiar tu última confirmación:

    $ git commit --amend

    Esto supone que no tienes ningún otro archivo agregado a tu área de preparación (es decir, no ejecutaste git add My_File sin confirmarlo también).

  2. Envía tu "cambio" a Github, usando la opción --force porque el mensaje de confirmación de Git es parte de tu confirmación existente, por lo que estás cambiando el historial en tu rama.

    $ git push --force

Quiero reestructurar múltiples cambios en una sola rama.

  1. Opcional pero muy recomendable: recuperar cambios de Github.

    $ git switch master$ git fetch$ git pull

    Esto garantiza que incorpore directamente cualquier otro cambio en su rama en el orden en que se fusionaron en master.

  2. Para reestructurar su trabajo, cambie la base de su sucursal y realice los cambios necesarios. Rebasar a master significa cambiar la confirmación principal de su primera confirmación en su rama:

    $ git rebase --interactive master

    Reemplace la primera palabra pick para modificar la confirmación.

    • Utilice e para realizar cambios reales en su confirmación. ¡Esto interrumpe tu rebase!

    • Utilice f para combinar una confirmación con su padre.

    • Utilice d para eliminar completamente la confirmación de su rama.

    • Mueva las líneas para cambiar el orden de sus cambios.

      Después de realizar un cambio de base exitoso, sus propias confirmaciones se encuentran encima de la última confirmación de master.

Quiero copiar una confirmación de otra rama.

  1. Obtenga el ID de confirmación de una rama estable (por ejemplo, una rama denominada 3.3), utilizando la opción -n para limitar el número de confirmaciones.

    $ git log -n 5 3.3
  2. Replica los cambios seleccionando confirmaciones en tu rama. La opción -x agrega el ID de confirmación a su mensaje de confirmación. Esto solo se recomienda cuando se seleccionan confirmaciones de una rama estable.

    $ git switch My_Branch$ git cherry-pick -x Commit_ID

Mas consejos

En ATIX, ejecutamos una instancia de GitLab para compartir código, colaborar y automatizar pruebas y compilaciones internamente. Con la comunidad de código abierto que rodea el ecosistema Foreman, confiamos en Github.

Le recomiendo que siempre apunte el control remoto llamado origin en cualquier repositorio Git a su sistema de control de versiones interno. Esto evita la filtración de información a servicios externos al realizar un git push basado en pura memoria muscular.

Además, recomiendo utilizar un esquema de nombres fijo para los controles remotos. Siempre nombro el control remoto que apunta a mi propia instancia de GitLab origin, el proyecto de código abierto upstream y mi bifurcación en Github github.

Para foreman-documentation, el repositorio tiene un historial relativamente plano. Cuando trabajo con una estructura más compleja, tiendo a pensar en los repositorios Git de una manera muy visual con nodos (compromisos) que apuntan a nodos en líneas (ramas) que potencialmente se entrelazan. Herramientas gráficas como gitk o Git Cola pueden ayudarte a visualizar tu historial de Git. Una vez que haya comprendido completamente cómo funciona Git, puede pasar a los alias, si prefiere la línea de comando.

Antes de una gran rebase con muchos conflictos de fusión esperados, recomiendo crear una rama de "respaldo" con la que pueda ver rápidamente las diferencias. Tenga en cuenta que es bastante difícil eliminar confirmaciones de forma irreversible, así que pruebe en su repositorio Git local antes de realizar cambios importantes.

Git para escritores de tecnología

Git es de gran ayuda para los redactores técnicos. No sólo puedes usar Git para versionar tu propio contenido, sino que también puedes colaborar activamente con otros.

Artículos relacionados: