Aún recuerdo la primera vez que experimenté con un repositorio. Nunca he encontrado en mi vida un mejor ejemplo para la típica frase de «no subestimes a tu enemigo». No era la primera vez que descargaba archivos de un repositorio de GitHub. Este paso es muy sencillo: botón descargar y listo. Pero, ¿cómo se suben archivos?

Otros repositorios como Thingiverse son mucho más sencillos en este aspecto. Vas a tu perfil web, creas un nuevo proyecto, añades una descripción, imágenes, vídeo y subes los archivos necesarios manualmente. Y con manualmente quiero decir que hay un botón que pone «subir archivos». Seleccionas los que quieres subir y ¡listo!

Pero, ¿por qué es tan complejo GitHub? Esta respuesta está en su funcionamiento. Repositorios como Thingiverse solo están ahí para que la gente suba sus proyectos y otros se los descargen. Un repositorio software como GitHub permite su configuración junto con entornos de desarrollo de forma que varias personas puedan estar trabajando en un gran proyecto. Digamos que tiene muchísima más potencia. Cuando tienes que pegarte con GitHub en un proyecto grande en cuanto a personas y tiempo (yo tuve que hacerlo durante un año con un equipo de 9 personas) es cuando tienen sentido todos esos rollos de los commit y los merge.

Pero seamos justos: no todo el mundo necesita esa potencia de un repositorio. Lo que buscamos los usuarios normales es poder compartir pequeños documentos y pequeños proyectos creados por una única persona con los demás de forma gratuita. Es decir, sin tener que andar pagando un alojamiento ni un dominio.

Pues empecemos con el tutorial.

Instalación de git

sudo apt-get install git

Después configuramos los parámetros base:

git config --global user.name "Tu Nombre"
git config --global user.email "correo@dominio.com"

A continuacióne, creamos el repositorio local. Es decir, una carpeta donde alojaremos los documentos antes de subirlos. Lo normal es crear la carpeta antes de comenzar con el proyecto. Después realizar todo lo que quieras hacer e ir subiendo los cambios. Pero en mi caso (y el de muchos) lo que quiero es subir un proyecto que ya tengo creado. Lo que hago entonces es crear el respositorio local, copiar el proyecto dentro y finalmente subirlo. Cuando el repositorio ya esté subido puedes borrar el repositorio local, a menos que quieras seguir haciendo cambios y subiendo nuevas versiones.

Creación de un repositorio local

Debes utilizar este comando:

git init NombreDeTuCarpeta

Es importante que elijas bien el nombre. Te recomiendo que no incluyas espacios y, si lo haces, lo hagas con «_» porque luego ese nombre estará en el enlace a tu repositorio. Además, cuando crees el repositorio en GitHub es necesario que tenga el mismo nombre que la carpeta. Por lo que repito: es importante elegir el nombre adecuado a la primera.ste

Este comando creará una carpeta en tu carpeta personal. Esa es la «raíz» de git. Si quieres crearla en otro sitio puedes especificar la ruta.

Archivo README

El paso siguiente (en el orden que yo lo hago) es crear un archivo readme. Aunque puedes crearlo en GitHub al crear el repositorio. Pero yo prefiero hacerlo así porque puedo crearlo con el editor de texto que yo quiera.

Para ello debemos movernos hasta la carpeta del repositorio local. Al estar ubicados en ella podemos crear el archivo. Puedes hacerlo mediante la interfaz grafica (Nautilus o Thunar) o hacerlo mediante consola. Yo suelo hacerlo por consola con el siguiente comando:

atom nombreArchivo.extension

Uso este comando porque el editor de textos que utilizo es atom. Si quieres usar gedit cambias «atom» por «gedit». O si prefieres hacerlo sin necesitar la consola simplemente abres gedit, escribes tu archivo y lo guardas en la carpeta del repositorio local.

Si no quieres complicarte la vida puedes no crearlo y luego verás como puedes incluirlo más adelante.

Mi recomendación es que, o bien manualmente o bien desde GitHub.com, incluyas un buen archivo readme. Este archivo es lo primero que se verá de tu proyecto y es lo que explicará a cualquiera que lo vea en qué consiste. Normalmente yo siempre incluyo lo siguiente:

  • Explicación rápida en español
  • Enlaces adicionales de documentación (un vídeo de youtube explicativo, un enlace a esta web donde presento el proyecto)
  • Explicación en inglés (lo mismo del primer punto pero traducido al ingles)
  • Notas importantes: como por ejemplo si es necesario tener alguna librería instalada o permisos de terceros o alguna licencia. También en inglés y en español

Para que te hagas una idea, esto es lo que se ve cuando abres un proyecto en GitHub:

readme github

Ese texto que se ve es lo que incluye el archivo README. Como puedes ver, un buen archivo README como este que incluye información en inglés y en español y enlaces adicionales de documentación del proyecto, por muy pequeño que sea, hace mucho más atractivo el proyecto al usuario.

Indexar los archivos

Antes de subir los archivos debes indexarlos para poder navegar por ellos en el repositorio. Es muy simple. Un comando para indexar cada archivo:

git add archivo.extension

Siguiendo con el ejemplo de la última imagen, podemos ver que contiene 3 archivos. Pues puedes hacer 3 veces ese comando. Una vez con cada archivo. Esto es poco útil, ¿verdad? Si quieres añadir al índice todos los archvos qdel respositorio local (que es lo más habitual) debes cambiar el nombre del archivo por un punto. Tal que así:

git add .

De esta forma incluiremos todos los archivos dentro de la carpeta o bien, si hemos editado, incluiremos todos los archivos teniendo en cuenta los cambios.

Registrar los cambios en el índice

Después de crear el índice debemos hacer lo que en la jerga se conoce como un «commit». Con esto lo que hacemos es comprobar y guardar los cambios realizados. En caso de que sea la primera vez que subimos a ese repositorio, los cambios solo será añadir los archivos. Este paso es necesario antes de subir los cambios: si no se guardan los cambios en el índice no se modificará nada en el repositorio y nadie verá los cambios o los nuevos archivos. El commit se hace con un comando muy sencillo:

git commit

Pero normalmente viene bien dejar un mensaje para que se sepa qué se ha hecho en ese commit.  Cuando es un proyecto en el que solo trabajo yo, ese mensaje es la fecha del commit.

git commit -m "mensaje"

Ya tenemos listo nuestro índice con sus cambios y todo para poder subir los cambios o los nuevos archivos a GitHub.

Creación de un repositorio online público en GitHub

Este paso lo incluyo ahora porque normalmente yo creo el repositorio cuando ya he terminado el proyecto y quiero subirlo porque, como solo he trabajado yo en él, lo he tenido siempre en local o, como mucho, en dropbox. Pero si lo que quieres es compartir el progreso de un proyecto para trabajar con más gente o por la razón que sea, entonces este paso deberá ser el primero que hagas.

No necesitas ningún comando: vas a la web de GitHub, creas un usuario si no lo tienes, creas un nuevo repositorio y modificas los parámetros de creación (como la opción de incluir o no automáticamente un README) a tu gusto y listo. El nombre debes tenerlo en cuenta para crear posteriormente el repositorio local o viceversa: si creas antes el repositorio local también debe coincidir el nombre al crear el repositorio en GitHub. Antes de poder subir el contenido debemos conectarnos a este repositorio:

git remote add origin https://github.com/miNombreDeusuario/MiRepositorio.git

Normalmente ese enlace puedes copiarlo tras crear el repositorio.

Subir los cambios al repositorio GitHub desde el local

Este es el último paso. Lo que se hace es empujar todo el contenido en local a GitHub para que puedan acceder los demás (o todos si es público).

git push origin master

Nos pedirá autencicación con usuario y contraseña. Para poder subir los cambios el usuario y contraseña introducidos deben ser los del propietario del repositorio o bien los de un usuario de GitHub con autorización para editar dicho proyecto. Si no es así, no podrás subir los cambios.

Conlusión: subir cambios de un proyecto ya creado

Si lo que tienes es un proyecto clonado en local de tu repositorio GitHub y has hecho algún cambio en algún archivo, los pasos que debes seguir para subir los cambios son:

  1. Actualizas el índice: git add .
  2. Guardas los cambios: git commit -m "mensaje"
  3. Subes los cambios: git push origin master

Al principio cuesta un poco hacerse al manejo de estos sistemas, pero según lo utilizas cas acostumbrándote.