Vademécum

Configuración del git local

Tras instalar es conveniente antes de empezar indicar cuál es el usuario que realizará los cambios:

$ git config --global user.name "Perico de los Palotes"
$ git config --glonal user.email "perico@example.com"

Y agilizar las autenticaciones:

$ git config --global credential-helper "cache --timeout=3600"

Esta última línea conserva en memoria la contraseña durante 1 hora. El problema de esta solución es que Github últimamente no permite el acceso mediante usuario y contraseña, con lo que tenemos dos alternativas prácticas:

• Utilizar un token personal de acceso, que sustituirá a la contraseña en las autenticaciones y se genera en la propia página de Github a través de Settings>Developer Settings>Access Personal Token. Estos tokens son muy largos y complicados de memorizar y digitalizar por lo que se hace indispensable usar un gestor de contraseñas. En Linux puede usarse el derivado de Gnome Keyring:

  $ git config --global credential-helper "/ruta/donde/este/git-credential-libsecret"
  $ git config --global credential.credentialStore secretservice

  Es probable que la distribución no disponga del complemento compilado y haya que hacerlo a mano como se explica en este tutorial.

  Hecho esto, la primera vez habrá que autenticarse usando el usuario y este largo token, pero las restantes veces no será necesario, porque las credenciales quedarán almacenadas en el gestor de contraseñas.

• Utilizar la autenticación OAuth para lo cual existe en las modernas distribuciones :command:`git-credential-oauth`. Instalada en el sistema, puede usarse esta configuración:

  $ git config --global credential-helper "cache --timeout=3600"
  $ git config --global credential-helper oauth

  De esta forma, al autenticarnos, el proceso de validación nos derivará el navegador para nos validemos y durante una hora las credenciales serán recordadas. Es importante que este sea el orden (primero la declaración de usar la caché), porque de lo contrario la caché no funcionará.

Creación de un repositorio

Al crear un repositorio tenemos dos alternativas:

• Clonar un repositorio ya creado.
• Crear uno ex novo.

Clonación

$ git clone https://github.com/sio2sio2/proyecto.git

Creación

$ mkdir proyecto
$ cd proyecto
$ git init
$ cat > .gitignore
**.bak
**.swp
$ echo "Documentacion..." > README.rst

Note

,gitignore excluye ficheros que no queramos que formen parte del repositorio. En este caso, hemos incluido copias de seguridad y archivos de intercambio de vim. La notación **.ext` significa todo fichero con la extensión indicada esté en el subdirectorio que esté.

Si se desea crear un nuevo repositorio en Github a partir de este nuevo, hay dos posibilidades:

• Crearlo a través de la web sin inicializarlo (o sea sin crearle un README.md),

• Crearlo a través de la API REST de Github, después de haber definido un token apropiado, esto es, un token que tenga habilitado al menos el alcance public_repo:

  $ wget -qO - -S --header "Authorization: token XXXXXXX" \
      --post-data '{"name": "proyecto", "description": "Una descripción del proyecto"}' \
      https://api.github.com/user/repos

para después realizar una Actualización y finalmente:

$ git remote add origin https://github.com/sio2sio2/proyecto.git
$ git push -u origin master

Actualización

Desde local

Si se han modificado ficheros en el repositorio local, pueden comprobarse los cambios del siguiente modo:

$ cd proyecto
$ git status  # Conocemos la rama en la que estamos y cuáles son los ficheros.
$ git diff    # Si queremos ver las diferencias entre los ficheros.
$ git diff -- fichero  # Para ver los cambios en el fichero referido.

Para llevar a cabo la actualización:

$ git add --all .
$ git commit -m "Comentario que describa la actualización"

Si la actualización requiere un comentario más exaustivo. se puede utilizar un fichero con sintaxis Markdown:

$ git commit -F comentario.md

Por último, si queremos sincronizar con el directorio remoto:

$ git push

Desde remoto

Si ya se disponía de una copia local del repositorio, pero la versión remota de éste cambió (p.e. porque otro desarrollador realizó cambios), puede consultarse si hay actualizaciones así:

$ cd proyecto
$ git fetch

Esto orden no realiza ningún cambio: simplemente analiza el estado del directorio local y del repositorio remoto y nos informa de si hay actualizaciones pendientes. Tocaría ahora comprobar cuáles son exactamente estas actualizaciones para lo que podríamos hacer:

$ git log HEAD..origin/main

si simplemente queremos ver qué commits se han llevado a cabo o:

$ git diff HEAD origin/main

para observar todas las diferenciias exhaustivamente. Si quisiéramos aplicar los cambios, habría que hacer finalmente:

$ git pull

Note

Se puede hacer un pull sin necesidad de hacer antes un fetch.

Warning

Tenga en cuenta que es común que un proyecto disponga de distintas ramas.

Ramas

Las diversas ramas de un mismo repositorio permiten tener simultáneamente distintas variantes del desarrollo. Por ejemplo, un desarrollador puede abrir una rama nueva para implementar una nueva funcionalidad y, cuando la tenga lista y se apruebe su inclusión, fusionarla con la rama principal.

La rama principal (la que se crea al crear el repositorio) se llama master. Es común también crear otra rama llamada development donde van convergiendo las distintas ramas que aparecen y desaparecen según las necesidades.

Creación

$ git checkout -b development

Esto clona la rama en la que se esté actualmente (supongamos que master) en otra llama development y nos camb ia a ella. Ahora si se hace:

$ git status

Comprobaremos que nos encontramos en la rama development. Ahora podemos realizar cambios sobre esta rama y actualizarma como ya se ha visto. Si queremos subir la rama al servidor de Github:

$ git push -u origin development

pero sólo esta primera vez para sincronizar la rama con una rama aún inexistente en el servidor también llamada development. A partir de este momento, las siguientes sincronizaciones sí podremos hacerlas como ya se indicó:

$ git push

Cambio

Para cambiar entre ramas:

$ git checkout master

donde master es el nombre de la rama a la que queremos cambiar.

Comparación

Si queremos comprobar qué commits hay de diferencia entre una y otra rama:

$ git log rama1..rama2

y si queremos conocer en concreto todos los cambios:

$ git diff rama1..rama2

aunque, como siempre ocurre con diff, se puede restringir aquellos de lo que queremos obtener las diferencias:

$ git diff rama1..rama2 -- ruta/hacia/algun/sitio

Fusión

Para fusionar la rama development con con la actual (master):

$ git merge development

Borrado

Para borrar una rama local:

$ git branch -d development

Y si se quiere borrar del repositorio remoto:

$ git push origin :development

Versiones

Para etiquetar un estado como versión:

$ git tag -a v1.0 -m "Versión 1.0"
$ git push --tags

Para eliminar una etiqueta en local basta con:

$ git tag -d v1.0

y para eliminarla en el repositorio remoto, se hace de la misma forma que cuando se eliminan ramas:

$ git push origin :v1.0

Regresión

Commit antiguo

En alguna ocasión puede ser útil volver a un estado antiguo. Para ello podemos crear una rama independiente:

$ git checkout -b test

y cambiar al commit que deseemos:

$ git log --oneline
f446e5e (HEAD -> test) Comentario...
8abe916 Comentario...
2c595db Comentario...
bfe76b5 Comentario...
$ git reset 2c595db
$ git restore .

Archivos

Si queremos deshacer los cambios hechos en un archivo que aún no se han fijado con un commit tenemos dos posibilidaes:

• Si ya se hizo un git add (el archivo aparece en verde al ahcer un status), podemos hacer:

  $ git restore --staged --worktree -- path/archivo

  Si se prescinde de --worktree el archivo quedará en el estado anterior al git add (en rojo). Si se especifica un directorio se restaurán todos los archivos modificados dentro de él.

• Si el archivo está modificado, pero sin haber hecho un git add (aparece en rojo):

  $ get restore -- path/archivo

  Esto eliminará todos los cambios en el archivo.

Varias cuentas

Cuando se tienen varias cuentas en Github (p.e. una personal y otra de trabajo) nos encontraremos con el problema que el gestor de contraseñas, en principio, almacena estas credenciales atendiendo únicamente el nombre de máquina (github.com), por lo que únicamente podremos usar unas únicas credenciales. Tenemos al menos tres alternativas para solucionarlo:

1. Usar el nombre del usuario como parte del nombre de máquina, es decir, en vez de haber relacionado directorio local con repositorio remoto así:

   $ git remote add origin https://github.com/sio2sio2/proyecto.git

   deberíamos relacionarlo así:

   $ git remote add origin https://sio2sio2@github.com/sio2sio2/proyecto.git

   Y en caso de que está relación ya la hubiéramos hecho, aún podríamos acceder al archivo .git/config y editar la URL en la directiva correspondiente para añadir el usuario al nombre.

   La ventaja de este procedimiento es que no necesitaremos introducir nuevamente el token cada vez que creemos un repositorio relacionado con el usuario.

   Esta técnica parece no funcionar. Al menos con :command:`git-credential-libsecret`

2. Añadir a la configuración global:

   $ git config --global credential.useHttpPath "true"

   que provoca que al apuntar las credenciales en el gestor se use toda la URL y no solamente el nombre de máquina. La desventaja de esta solución es que cada vez que creemos un repositorio nuevo, tendremos que facilitar las credenciales.

3. Usar sendos métodos de validación (helper) diferentes para lo que podemos usar la configuración condicional que trataremos después o definir las credenciales dependiendo de cuál sea la ruta con la que sincronicemos:

   [credential "https://github.com/sio2sio2/"]
   helper = /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret
   credentialStore = secretservice
   [credential "https://github.com/otrousuario/"]
   helper = "cache --timeout=7200"
   helper = oauth

Cualquiera de las tres alternativas nos solucionaría la autenticación. Sin embargo, también es probable que queramos cambiar quién será el que rece como autor de los cambios. Para ello puede utilizarse la configuración condicional introducida a partir de :program:`git` 2.13. De este modo, si tuviéramos la prevención de que los desarrollos de uno de los usuarios siempre estuvieran dentro de la misma ruta podríamos hacer:

# Esto es ~/.gitconfig
[user]
name = Perico de los Palotes
email = perico@example.com

[includeIf "gitdir:~/Programacion/Trabajo/"]
path = ~/Programacion/Trabajo/.gitconfig

Y en ese segundo archivo de configuración:

# Esto es ~/Programacion/Trabajo/.gitconfig
[user]
name = Pedro Palotes
email = pedropalotes@corporacion.com