Guía rápida de Github

From FdIwiki ELP
Jump to: navigation, search

GitHub es una plataforma en la que al registrarse puedes añadir y modificar proyectos de software para tenerlos en la red y poder compartirlos con la comunidad, aunque también puede añadirse código de forma privada. GitHub ofrece la funcionalidad del control de versiones distribuido de Git y añade sus propias características.

El propósito de esta guía rápida es que conozcas lo básico sobre cómo funciona y cómo usar GitHub. Habrán muchas palabras del entorno de GitHub que aprenderás y que aparecerán remarcadas, se recomienda buscarlas en la sección Glosario.

También puedes consultar el artículo GitHub (Comandos).


Git

Git es uno de los más amplios sistemas de gestión de código enfocado al desarrollo. Pertenece al apartado de los dvcs (Distributed Version Control System) o Sistemas de control de versiones distribuidos como SVN, Mercurial, Dars, y su punto fuerte es la velocidad, integridad de datos y soporte para flujos de trabajo distribuidos no lineales. Fue diseñado y desarrollado en 2005 por los desarrolladores del kernel de Linux con Linus Torvalds entre ellos, para el desarrollo del kernel de Linux.

Como muchos otros DVCS, el directorio de trabajo de Git contiene toda la información acerca del historial y versiones (datos o codigo) de todas sus ramas o commits. Gracias a esta estructura de directorios y ficheros se puede regresar a cualquier punto del desarrollo. Además, igual que el kernel de Linux, Git es software libre distribuido bajo la licencia de GNU General Public License version 2.

GitHub

GitHub es el host más grande para repositorios Git. Provee control de acceso y varias características de colaboración como wikis, administración de tareas, seguimiento de bugs(issues), hitos(milestones), etc. Tiene dos tipos de cuentas[1]:

  • Pública (gratuita): Tienes derecho a todos los repositorios no ocultos que quieras. Está enfocada a los proyectos de software libre.
  • Privada (de pago): Hay múltiples tipos y precios, y en función de eso amplían más o menos el número de repositorios privados. Además varían en función del espacio que ponen a tu disposición.

Una de las funciones que mas fomentar la participación de la comunidad es que permite colaborar con proyectos de otros usuarios gracias a que ofrece una localización centralizada para compartir tus repositorios en una interfaz web.

Tiene entre otras funciones (para ambos tipos de cuentas):

  • Todo esto desde la interfaz web, pues al contrario que Git, tiene negado el uso de linea de comandos.
  • Gestión de errores (issues) con etiquetas, hitos, usuario asignado y motor de búsqueda.
  • Pull requests with code review and comments. Pull request (petición de incorporación de ficheros) con un vistazo del código y comentarios.
  • Gráficos de estadísticas.

La magia de GitHub y Git radica en que GitHub alberga un repositorio al que llamaremos Repositorio remoto y en nuestro ordenador tenemos otro al que llamaremos Repositorio local. Aunque igualmente tenemos todas las ventajas de Git trabajando localmente, el verdadero potencial esta en trabajar en equipo. De este modo, usando un repositorio remoto contenido en GitHub y cada participante una copia local de este, cada uno puede empujar (push) sus cambios al remoto y que los demas lo vean y lo discutan.

Este viene a ser el flujo de trabajo básico de GitHub:

  • CREA UNA RAMA O BRANCH

Crear en tu proyecto una rama nueva donde puedes hacer cambios y experimentar de forma segura.

  • AÑADIR COMMITS
  • ABRIR UN PULL REQUEST

Usa los pull request para obtener un feedback de los cambios.

  • DISCUTE Y REVISA LOS CAMBIOS
  • UNE(MERGE) Y DESPLIEGA(DEPLOY) EL RESULTADO

Une tu rama con tus cambios a la rama principal y prueba el resultado.

Comenzar

La primera cosa que necesitas es crear una cuenta en GitHub https://github.com,

Instalar y configurar Git

Git es el responsable de la parte que pasa localmente en tu ordenador. Podrás usar los comandos de git en el terminal. Es recomendable entender Git para usar mejor GitHub.

  • Descarga e instalación:
    http://git-scm.com/downloads
  • Configuración
    • tu nombre de usuario para etiquetar tus commits: git config --global user.name YOUR_NAME
    • mail asociado: git config --global user.email YOUR_EMAIL_ADDRESS

Crear una repo para nuestro proyecto

Creamos un repositorio en GitHub.com:

  • Le damos un nombre y una pequeña descripción.
  • Elegimos si queremos que sea una repo pública o privada.[1]
  • Seleccionamos iniciar la repo con un README. Esto creará un archivo markdown README.md donde aparecerán el nombre y la descripción, se podrá editar después. Será la carta de presentación de tu repositorio en GitHub.com.
  • Podemos añadir archivos .gitignore, que especifica a qué archivos no debe hacer seguimiento, Git los ignorará cuando hagas un commit. GitHub te ofrece una lista oficial de los archivos .gitignore para muchos SO, entornos y lenguajes. Por ejemplo, si trabajas desarrollando android podemos usar Android.gitignore para guardar solo los archivos que queremos y no todos los archivos que se generan en la compilación. (más info)
  • Y añadimos una licencia al repositorio, si no eliges ninguna tendrás por defecto Copyright. Se generará un archivo de licencia en tu repo.

O crear una repo nueva a partir de un directorio en nuestro ordenador con varios ficheros . Vamos a la terminal, nos ubicamos en el directorio e introducimos git init, esto creará un repositorio en nuestra cuenta con el nombre del directorio.

Y otro en nuestro pc:

  • Nos posicionamos en el directorio donde queramos el repositorio
  • Escribimos:

git init Esto transforma el directorio actual en un repositorio (en blanco).

Clonar el repositorio a tu ordenador

Para esto se usa el comando git clone reposotorio que como bien dice "clona" el reposotorio indicado en forma de http[s]://www.web.com/nombre.git en el directorio actual (usar sobre un repositorio en blanco).

Has creado un clon que es una versión local e identica de tu proyecto. Ahora tienes una carpeta con los contenidos del repositorio. Además, por defecto, ahora te encuentras en la rama principal (master) de tu repo.

Trabajar en un repositorio

Ahora veremos el flujo típico de trabajo con GitHub. Para más información sobre los comandos puedes consultar el artículo GitHub (Comandos).

Preparar el área de trabajo para que esté actualizado

  • Ir repositorio. En la terminal nos dirigimos al directorio de nuestro repositorio con ayuda de:
    cd project
  • comprobar estado repositorio
    git status
  • actualizar datos (fetch+merge o pull)
    git fetch [alias]
    git merge [alias]/[branch]
    git pull [alias]

Trabajar en una nueva rama

  • crear nueva rama
    git branch branchname
  • ir a la nueva rama
    git checkout branchname

Modificar y hacer commit

  • realizar cambios ficheros. Crear, eliminar y editar archivos, tanto por comandos (nano, vim, emacs) o editores o entornos.
  • comprobar estado del repositorio status
    git status
  • añadirlos al staging area
    git add files, git add *, git add .
  • realizar el commit
    git commit -m message

Para hacer merge de tu rama1 y tu rama2

  • ir a la rama superior
    git checkout rama1
  • realizar merge
    git merge rama2

Actualizar el repositorio remoto de GitHub.com

  • realizar push
    git push
  • volver comprobar estado repositorio
    git status

Fork

Un fork es una copia de un repositorio, se crea la copia en tu cuenta. Hacer fork permite experimentar libremente con el repositorio sin afectar el original. Para crear un fork solo pulsa el botón fork de la página del repositorio de que quieres tener una copia. Normalmente, los forks se usan para:

  • Proponer cambios al proyecto de otro usuario. Por ejemplo para arreglar bugs, en lugar de abrir un issue informando del bug que has encontrado, es mejor hacer un fork, hacer el arreglo y finalmente hacer un pull request al dueño del repositorio. Si al creador le gusta tu trabajo lo aceptará y hará pull.
  • Usar el proyecto de otro usuario como punto de partida para tu propio proyecto. Asegúrate de leer la licencia de ese proyecto antes.

Se puede hacer fork en la página del proyecto en GitHub.com. A los proyectos que te interesen puedes darles un watch o una estrella.

  1. Crea una copia local del fork:
    Ve a tu fork en GitHub.com y copia el URL y haz el clon en el terminal.
    git clone https://github.com/YOUR_USERNAME/YOUR_FORK
    Ahora tienes una copia local de tu fork del repositorio.
  2. Configura Git para sincronizar tu fork con el original.
    • Necesitas el URL del original, obténlo en GitHub.com.
    • En el terminal ubícate en el fork (la copia) que has hecho. Si introduces git remote -v verás la configuración actual de repositorio remoto para tu fork. (de dónde haces fetch y a dónde haces push)
      git remote -v
      origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
      origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
    • Añade otro repositorio remoto a tu fork. Introduce git remote add upstream, seguido del URL del proyecto original:
      git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPO.git
    • Para verificar que el nuevo repositorio upstream se ha añadido, introduce git remote -v otra vez. Verás el URL de tu fork como origin, y el URL del repositorio original como upstream (son los nombres de los repositorios remotos a los que está conectada tu copia local).
      git remote -v
      origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
      origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
      upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch)
      upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)
  3. Sincronizar tu fork
    Ahora sincronizaremos tu copia local con el repositorio original (estamos actualizando la copia local, para actualizar tu fork en GitHub debes hacer push de los cambios). Te aconsejamos que leas Branches antes de leer esto.
    • En el terminal ubícate en el directorio de la copia local (el fork)
    • Haz fetch (de las ramas y sus respectivos commits) de la repo upstream. Los commits hechos a master serán almacenados en una rama local, upstream/master.
      git fetch upstream
    • Haz checkout de la rama local master de tu fork: Cambias de contexto en el que trabajas, cambiamos a la rama master de nuestra copia local.
      git checkout master
      Switched to branch 'master'
    • Hacemos merge de los cambios de upstream/master en la rama master local. Esto sincroniza la rama master de tu fork con el repositorio upstream sin perder tus cambios locales.
      git merge upstream/master

Entre las cosas que puedes hacer con los forks son crear branches y abrir pull requests. (más info)

Branches

Prácticamente podemos pensar en ramas como contextos ya que, en la mayoría de casos, los usarás de esa forma. Las ramas te permiten construir nuevas características o probar ideas sin poner en riesgo la parte principal de tu proyecto. Puedes trabajar en una parte distinta del repositorio cada vez.

Cuando creas un repositorio, se tiene por defecto una rama llamada “master”. Puedes seguir trabajando en esta rama y tener solo una... Pero si tienes una nueva idea o característica en la que quieres trabajar, puedes crear una nueva rama que surge de la rama master, de esta manera, dejarás al master en su estado. Una rama es una versión paralela de la línea principal de desarrollo en el repositorio, o rama defecto (master).

Cuando creas una rama, estás haciendo una copia de la rama original en el estado en el que estaba en ese momento en el tiempo, como una foto instantánea. Si la rama original cambia mientras estás trabajando en tu nueva rama, no te preocupes, siempre puedes hacer pull de esas actualizaciones.

En GitHub, los desarrolladores, escritores y diseñadores usan las ramas para mantener los arreglos de bugs y cada característica separados de la rama master (rama de producción). Cuando una característica o arreglo está hecho puede hacerse un merge hacia el master.

  • crear una nueva rama
    git branch new_branch
  • cambiar de contexto o rama en la que estamos.
    git checkout new_branch
    git checkout master
  • crear una nueva rama y cambiarse a esa rama
    git checkout -b new_branch
  • ver la lista de ramas existentes
    git branch
  • ver el historial de commits de la rama actual
    git log
  • hacer merge de ramas en la rama master. Debemos estar en el contexto que queremos cambiar, en este caso, master.
    git checkout master
    git merge new_brach

Issues

Un issue es una nota en un repositorio acerca de algo que necesita nuestra atención. Si encuentras un bug en un proyecto que estás usando (y no sabes cómo resolverlo), tienes problemas con la documentación o tienes una pregunta, crea un issue. En GitHub puedes ponerles etiqueta, asignarlos a usuarios y hacer búsquedas. Se gestionan los issues desde GitHub.com. (más info)

Pull request

Los pull requests son el núcleo de la colaboración en GitHub. Cuando haces un pull request, estás proponiendo tus cambios y pidiendo que alguien haga pull de tu contribución al proyecto. Los pull requests te permiten comparar el contenido de dos ramas. Los cambios, adiciones y sustracciones serán mostrados en verde y rojo, llamamos a esto diffs.

Tan pronto como haces un cambio, puedes abrir un pull request. Estos se usan para empezar discusiones sobre el código aunque no esté terminado. De esta manera, puedes obtener feedback o incluso ayuda. Puedes abrir un pull request en tu propio repositorio y hacer merge tú mismo. Perfecto para aprender antes de trabajar en grandes proyectos. Los pull request se gestionan desde GitHub.com. (más info)

Watch y star

Uno puede hacer watch o dar una estrella a un proyecto. La gran diferencia entre watch y star está en las notificaciones. En el caso de watch, recibirás notificaciones de todas las discusiones: issues, pull request, comentarios en commits y toda clase de comentarios. Si no has hecho watch y participas en una discusión, recibirás notificaciones de esa discusión.

Y en el caso de star, estás mostrando tu apreciación y la estás guardando en tu lista de estrellas para poder seguirlas sin tener que recibir notificaciones en tu timeline. Además cualquier repositorio al que hayas hecho watch previamente, estará en tu lista de stars. Existe también lo llamado auto-watch, cuando te conceden acceso para hacer push en un repositorio, automáticamente se añade a tu lista de watch.

Glosario

Blame
Este feature describe la última modificación de cada línea de un archivo, generalmente se ve la revisión, autor y hora. Útil para, por ejemplo, averiguar cuando ha sido añadida una nueva característica o qué commit dio lugar a un bug en particular.
Branch
Un branch o rama es una versión paralela de un repositorio. Está contenida en el repositorio pero no afecta a la rama principal llamada MASTER branch. Nos permite trabajar libremente sin afectar la última versión “viva”. Una vez hechos los cambios que queremos en la rama podemos unirla (merge) a la rama principal y publicar los cambios.
Checkout
Cuando haces checkout de distintas ramas, cambias el contexto en el que estás trabajando. Puedes cambiar de rama/contexto cada vez que quieras.
Clon
Un clon es una copia del repositorio que vive en tu ordenador en lugar del servidor web. Clonar nos permite editar los archivos en tu editor favorito y usar Git para hacer seguimiento de tus cambios sin tener que estar online. El clon está, sin embargo, conectado a la versión remota para que los cambios entre ambos se sincronicen. Puedes hacer push de tus cambios locales para cambiar la versión remota cuando estés online.
Colaborador
Una persona con acceso de lectura y escritura al repositorio que ha sido invitado a contribuir por el dueño del repositorio.
Commit
Un commit es un cambio individual hecho a un archivo (o varios). Como cuando guardas un archivo, pero con Git con cada versión que guardas crea un ID único (a.k.a. SHA o hash) que permite mantener guardado qué cambios han sido hechos, cuando y por quién. Los commits suelen tener un mensaje de commit con una descripción concisa de los cambios que guardas.
Contribuidor
Es una persona que ha contribuido a un proyecto cuando su pull request ha sido unido (merged) pero no tiene acceso de colaborador.
Diff
Un diff es la diferencia de los cambios entre dos commits, o cambios guardados. Nos mostrará visualmente qué ha sido agregado o borrado de un archivo desde su último commit.
Fetch
Fetch o extraer los últimos cambios de un repositorio online sin unirlos (merge) a la versión actual con la que trabajas localmente en tu ordenador. Una vez extraídos puedes compararlos con tus ramas (branches) locales.
Fork
Un fork es una copia personal del repositorio de otro usuario que se añade a tu cuenta. De esta manera puedes hacer cambios al ese proyecto sin afectar al original. Los forks siguen conectados al original permitiendo la posibilidad de hacer un pull request al autor del proyecto original. También se puede mantener actualizado el fork a partir del original (pull in updates).
Git
Git es un programa open source de control de versiones de archivos de texto. Fue escrito por el autor de sistema operativo Linux y es el núcleo tecnológico sobre el que gitHub (interfaz social y de usuario) ha sido construido.
head
Un nombre que hace referencia al commit último de una rama (la punta de la rama). Los heads se almacenan en el directorio $GIT_DIR/refs/heads/ (excepto cuando se usan packed refs (See git-pack-refs(1).)).
HEAD
Es el último commit la rama actual o activa. Tu árbol de trabajo o repositorio local con todas sus ramas normalmente deriva del estado del árbol actual por donde HEAD hace referencia. HEAD hace referencia a uno de los heads de tu repositorio (excepto cuando se usa detached HEAD , caso en el que HEAD referencia un commit arbitrario).
Issue
Los issues son mejoras que se sugieren, tareas o preguntas, todos relacionados con el repositorio. Los issues pueden ser creados por cualquier usuario (en repos públicas, claro) y son moderados por los colaboradores de la repo. Cada issue contiene su propio foro de discusión, puede ser etiquetado y asignarse a un usuario.
Markdown
Es un lenguaje de marcas ligero. Permite añadir enlaces, bullets, listas, etc. con marcas. Destaca su uso en el archivo README.md de las repos y puedes ver la semántica here. https://help.github.com/articles/github-flavored-markdown/
master
La rama o branch de desarrollo por defecto. Cuando creas un repositorio, una rama llamada “master” es creada y se convierte en la rama activa.
Merge
Mezclar o merge es coger los cambios de un branch (de la repo o de un fork) y aplicar los cambios a otro branch. Suele ocurrir con un Pull Request (que se puede entender como una petición de merge), o con el comando. Un merge puede hacerse automáticamente vía Pull Request en GitHub.com (la interfaz web) si no hay conflictos en los cambios o puede hacerse con la línea de comando.
Open Source
Un software open source es aquel que puede ser libremente usado, modificado y compartido (tanto el original como la modificación) por cualquier persona. Este concepto también se ha extendido como una filosofía de colaboración en el que los materiales de trabajo están disponibles online para todos para hacer fork (hacer copias), modificar, discutir y contribuir.
Organizaciones
Organizaciones en GitHub son grupos de dos o más usuarios que suelen representar organizaciones en la vida real. Son administradas por usuarios y pueden contener tanto repos como equipos.
Repositorios privados
Las repos privadas son aquellas donde solo el creador y los colaboradores que invita pueden ver y contribuir. [1]
Pull
Hacer pull se refiere a cuando haces fetch (extraes cambios hacia tu copia local) y haces merge. Pull = fetch + merge. Por ejemplo, si alguien ha editado el archivo remoto en el que tú también estás trabajando (localmente), querrás hacer pull de esos cambios para que tu copia local esté actualizada.
Pull Request
Son cambios propuestos por un usuario a un repositorio y pueden ser aceptados o rechazados por los colaboradores de la repo. Como los issues, estos también tienen sus propios foros de discusión.
Push
Hacer push se refiere a enviar tus cambios a un repositorio remoto (en GitHub.com). Por ejemplo, si haces cambios localmente, querrás hacer push de esos cambios para que el resto tenga acceso a ellos.
Remoto (copia remota)
Es la versión de algo que está alojado en un servidor, como GitHub.com. Puede estar conectado a clones locales para que se sincronicen.
Repositorios o repos
Un repositorio es el elemento más básico de GitHub. Se pueden entender como la carpeta de un proyecto. Un repositorio contiene todos los archivos del proyecto, incluyendo la documentación, además almacena la historia de revisiones. Los repositorios pueden tener múltiples colaboradores y pueden ser públicos o privados.
SSH Key
Las llaves SSH o SSH keys son una manera de identificarte en el servidor online, usando un mensaje encriptado. Es como si tu ordenador tiene una contraseña propia y única para otro servidor. GitHub usa SSH keys para asegurar la transferencia de información desde GitHub.com a tu ordenador. (Secure SHell o intérprete de órdenes seguro)
Staging area
Es el área de preparación donde se encuentran los ficheros sobre los que la acción de commit tendrá efecto. Se trata de un archivo con la lista de estos ficheros, también es conocido como el "índice".
Upstream
Cuando hablamos de una rama o un fork, a la rama principal (master) del repositorio original se le hace referencia como el “upstream”, ya que es el sitio principal de donde vendrán los otros cambios. La rama o fork en el que estás trabajando es llamado “downstream”.
Usuario
Los usuarios son cuentas personales de GitHub. Cada usuario tiene un perfil personal y puede tener múltiples repositorios, públicos o privados. Pueden crear organizaciones o ser invitados a ellas, o colaborar en repositorios de otros usuarios.


Véase también

Referencias

  1. 1,0 1,1 Si vinculas tu cuenta de GitHub con la UCM recibes la posibilidad de tener hasta 5 repositorios privados. Puedes hacerlo aquí, el Student developer pack ofrece además muchos otros beneficios.