From 1030ce8963c48bddf416e246c11f7876351e5e0a Mon Sep 17 00:00:00 2001 From: Fernando Raya Date: Mon, 20 May 2024 13:45:20 +0200 Subject: [PATCH] Add initial git-avanzado --- doc/github-avanzado.adoc | 241 ---------------------------- doc/source/git-uso-avanzado.rst | 272 ++++++++++++++++++++++++++++++++ doc/source/github-avanzado.rst | 271 +++++++++++++++++++++++++++++++ 3 files changed, 543 insertions(+), 241 deletions(-) delete mode 100644 doc/github-avanzado.adoc create mode 100644 doc/source/git-uso-avanzado.rst create mode 100644 doc/source/github-avanzado.rst diff --git a/doc/github-avanzado.adoc b/doc/github-avanzado.adoc deleted file mode 100644 index 9a17627..0000000 --- a/doc/github-avanzado.adoc +++ /dev/null @@ -1,241 +0,0 @@ -== Github avanzado - -Esta sección trata de cómo colaborar con proyectos de terceros. - -=== Clonar un repositorio - -Nos vamos a la web del proyecto en el que queremos colaborar. -Pulsamos en el botón de fork y eso creará una copia en nuestro perfil. - -image::github-proyect.png[Barra de información de proyecto] - -Una vez se termine de clonar el repositorio, nos encontraremos con el -espacio de trabajo del mismo: - -* En la parte superior información sobre los commits, ramas, etiquetas, -etc. -* Justo debajo un explorador de archivos. -* En la parte derecha un selector para cambiar de contexto entre: -explorador de código, peticiones de colaboración (pull request), wiki, -configuración, etc. -* Justo abajo a la derecha información sobre como clonar localmente o -descargar un proyecto. - -image::github-main.png[Espacio de trabajo] - -Github nos permite clonar localmente un proyecto por tres vías: HTTPS, -SSH y Subversion. Seleccionamos SSH y copiamos el texto que después -añadiremos a la orden `git clone` como en la primera línea del siguiente -grupo de órdenes: - -.... -$ git clone git@github.com:miusuario/miniblog.git -$ cd miniblog -$ composer.phar install -$ php console create-schema -.... - -Lo que hace el código anterior es: - -[arabic] -. Clona el repositorio localmente -. Entramos en la copia - - -==== Sincronizar con el repositorio original - -Cuando clonamos un repositorio de otro usuario hacemos una copia del -original. Pero esa copia es igual al momento en el que hicimos la copia. -Cuando el repositorio original cambie, que lo hará, nuestro repositorio -no se actualizará solo. ¡Son dos repositorios diferentes! Necesitamos -una manera de poder incorporar los cambios que vaya teniendo el -repositorio original en el nuestro. Para eso crearemos una nueva rama -remota. Por convenio, y como vimos anteriormente, ya existe una rama -remota llamada _origin_ que apunta al repositorio de donde clonamos el -proyecto, en este caso apunta a nuestro fork en github: - -.... -$ git remote show origin -* remote origin - Fetch URL: git@github.com:miusuario/miniblog.git - Push URL: git@github.com:miusuario/miniblog.git - HEAD branch (remote HEAD is ambiguous, may be one of the following): - develop - master - Remote branches: - develop tracked - master tracked - Local branch configured for 'git pull': - master merges with remote master - Local ref configured for 'git push': - master pushes to master (up to date) -.... - -También por convenio, la rama remota que hace referencia al repositorio -original se llama _upstream_ y se crea de la siguiente manera: - -.... -$ git remote add upstream git@github.com:sgomez/miniblog.git -$ git remote show upstream -* remote upstream - Fetch URL: git@github.com:sgomez/miniblog.git - Push URL: git@github.com:sgomez/miniblog.git - HEAD branch: master - Remote branches: - develop new (next fetch will store in remotes/upstream) - master new (next fetch will store in remotes/upstream) - Local ref configured for 'git push': - master pushes to master (local out of date) -.... - -En este caso, la URI debe ser siempre la del proyecto original. Y ahora -para incorporar actualizaciones, usaremos el merge en dos pasos: - -.... -$ git fetch upstream -$ git merge upstream/master -.... - -Recordemos que _fetch_ solo trae los cambios que existan en el -repositorio remoto sin hacer ningún cambio en nuestro repositorio. Es la -orden _merge_ la que se encarga de que todo esté sincronizado. En este -caso decimos que queremos fusionar con la rama _master_ que está en el -repositorio _upstream_. - -==== Creando nuevas funcionalidades - -Vamos a crear una nueva funcionalidad: vamos a añadir una licencia de -uso. Para ello preferentemente crearemos una nueva rama. - -.... -$ git checkout -b add-license -$ echo "LICENCIA MIT" > LICESE -# el error es intencionado -$ git add LICESE -$ git commit -m "Archivo de licencia de uso" -.... - -En principio habría que probar que todo funciona bien y entonces -integraremos en la rama _master_ de nuestro repositorio y enviamos los -cambios a Github: - -.... -$ git checkout master -$ git merge add-license --no-ff -$ git branch -d add-license -# Borramos la rama que ya no nos sirve para nada -$ git push --set-upstream origin add-license -# Enviamos la rama a nuestro repositorio origin -.... - -Si volvemos a Github, veremos que nos avisa de que hemos subido una -nueva rama y si queremos crear un pull request. - -image::github-pushed.png[Aviso de nueva rama] - -Pulsamos y entramos en la petición de _Pull Request_. Este es el momento -para revisar cualquier error antes de enviar al dueño del repositorio. -Como vemos hemos cometido uno, nombrando el fichero, si lo correguimos -debemos hacer otro push para ir actualizando la rama. Cuando esté lista -volvemos aquí y continuamos. Hay que dejar una descripción del cambio -que vamos a hacer. - -image::github-mergerequest.png[Creando un Pull Request] - -Una vez hemos terminado y nos aseguramos que todo está correcto, -pulsamos _Send pull request_ y le llegará nuestra petición al dueño del -proyecto. - -image::github-pullrequest.png[Gestión de un _Pull Request_] - -Sin embargo, para esta prueba, no vamos a cambiar el nombre del archivo -y dejaremos el error como está. Así de esta manera al administrador del -proyecto le llegará el _Pull Request_ y la lista de cambios. Ahora en -principio, cabría esperar que el administrador aprobara los cambios, -pero podría pasar que nos indicara que cambiemos algo. En ese caso solo -habría que modificar la rama y volverla a enviar. - -.... -$ git mv LICESE LICENSE -$ git commit -m "Fix: Nombre de archivo LICENSE" -$ git push -.... - -Ahora sí, el administrador puede aprobar la fusión y borrar la rama del -repositorio. El panel de Github permite aceptar los cambios directamente -o informa de como hacer una copia de la rama ofrecida por el usuario -para hacer cambios, como puede verse en la siguiente imagen. - -image::github-pullconversation.png[Conversación en un _PullRequest_] - -Una vez que se han aceptado los cambios, podemos borrar la rama y -actualizar nuestro repositorio con los datos del remoto como hicimos -antes. ¿Por qué actualizar desde el remoto y no desde nuetra rama -_add-license_? Pues porque usualmente el administrador puede haber -modificado los cambios que le hemos propuesto, o incluso una tercera -persona. Recordemos el cariz colaborativo que tiene Github. - -.... -$ git checkout master -$ git branch -d add-license -# Esto borra la rama local -$ git push origin --delete add-license -# Esto borra la rama remota. También puede hacerse desde la web. -.... - -==== Todo esto es algo complicado… - -Sí, lo es, al menos al principio. Git tiene una parte muy sencilla que -es el uso del repositorio local (órdenes tales como add, rm, mv y -commit). El siguiente nivel de complejidad lo componen las órdenes para -trabajar con ramas y fusionarlas (checkout, branch, merge, rebase) y por -último, las que trabajan con repositorios remotos (pull, push, fetch, -remote). Además hay otra serie de órdenes para tener información (diff, -log, status) o hacer operaciones de mantenimiento (fsck, gc). Lo -importante para no perderse en Git, es seguir la siguiente máxima: - -[IMPORTANT] -==== -No avanzar al siguiente nivel de complejidad, hasta no haber entendido -completamente el anterior. -==== - -Muy poco sentido tiene ponernos a crear ramas en github si aún no -entendemos cómo se crean localmente y para que deben usarse. En la parte -de referencias hay varios manuales en línea, incluso tutoriales -interactivos. También hay mucha documentación disponible en Github que -suele venir muy bien explicada. En caso de que tengamos un problema que -no sepamos resolver, una web muy buena es -http://stackoverflow.com/[StackOverflow]. Es una web de preguntas y -respuestas para profesionales; es muy difícil que se os plantee una duda -que no haya sido ya preguntada y respondida en esa web. Eso sí, el -inglés es imprescindible. - -=== Último paso, documentación. - -Github permite crear documentación. En primer lugar, generando un -archivo llamado `README.md`. También permite crear una web propia para -el proyecto y, además, una wiki. Para marcar el texto, se utiliza un -lenguaje de marcado de texto denominado _Markdown_. En la siguiente web -hay un tutorial interactivo: http://www.markdowntutorial.com/. Como en -principio, no es necesario saber Markdown para poder trabajar con Git o -con Github, no vamos a incidir más en este asunto. - -En el propio GitHub podemos encontrar algunas plantillas que nos sirvan -de referencia. - -Algunos ejemplos: - -* https://gist.github.com/PurpleBooth/109311bb0361f32d87a2[Plantilla -básica] -* https://github.com/othneildrew/Best-README-Template[Plantilla -avanzada] - -==== Documentación del curso - -Esta documentación está hecha en Asciidoc y pasada a PDF gracias a la -herramienta https://docs.asciidoctor.org[Asciidoctor]. - -El material está publicado con licencia -https://creativecommons.org/licenses/by-nc/4.0/deed.es[Atribución-NoComercial -4.0 Internacional (CC BY-NC 4.0)] diff --git a/doc/source/git-uso-avanzado.rst b/doc/source/git-uso-avanzado.rst new file mode 100644 index 0000000..4b30175 --- /dev/null +++ b/doc/source/git-uso-avanzado.rst @@ -0,0 +1,272 @@ +Uso avanzado de Git +=================== + +Deshacer cambios +---------------- + +Deshaciendo cambios antes de la fase de staging +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Volvemos a la rama máster y vamos a modificar el comentario que +pusimos: + +.. code-block:: console + + $ git checkout main + Previous HEAD position was 3283e0d... + Se añade un parámetro por defecto Switched to branch 'main' + +Modificamos `hola.php` de la siguiente manera: + +.. code-block:: dylan + +Y comprobamos: + +.. code-block:: console + + $ git status + # On branch main + # Changes not staged for commit: + # (use "git add ;..." to update what will be committed) + # (use "git checkout -- ..." to discard changes in working directory) + # + # modified: hola.php # + no changes added to commit (use "git add" and/or "git commit -a") + +El mismo Git nos indica que debemos hacer para añadir los cambios o +para deshacerlos: + +.. code-block:: console + + $ git checkout hola.php + $ git status + # On branch main + nothing to commit, working directory clean + $ cat hola.php + + +Deshaciendo cambios antes del commit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Vamos a hacer lo mismo que la vez anterior, pero esta vez sí +añadiremos el cambio al :term:`staging` (sin hacer :term:`commit`). + +Así que volvemos a modificar ``hello`` igual que la anterior ocasión: + +.. code-block:: dylan + + +Y lo añadimos al :term:`staging` + +.. code-block:: console + + $ git add hola.php + $ git status + # On branch main + # Changes to be committed: + # (use "git reset HEAD ..." to unstage) + # + # modified: hola.php + +De nuevo, Git nos indica qué debemos hacer para deshacer el cambio: + +.. code-block:: console + + $ git reset HEAD hola.php + Unstaged changes after reset: + M hola.php + $ git status + # On branch main + # Changes not staged for commit: + # (use "git add ..." to update what will be committed) + # (use "git checkout -- ..." to discard changes in working directory) + # + # modified: hola.php + # + no changes added to commit (use "git add" and/or "git commit -a") + $ git checkout hola.php + +Y ya tenemos nuestro repositorio limpio otra vez. Como vemos hay que +hacerlo en dos pasos: uno para borrar los datos del \_staging\_ y otro +para restaurar la copia de trabajo. + +Deshaciendo commits no deseados +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Si a pesar de todo hemos hecho un commit y nos hemos equivocado, +podemos deshacerlo con la orden ``git revert``. +Modificamos otra vez el archivo como antes: + +.. code-block:: dylan + + +Pero ahora sí hacemos commit: + +.. code-block:: console + + $ git add hola.php + $ git commit -m "Ups... este commit está mal." + main 5a5d067] Ups... este commit está mal + 1 file changed, 1 insertion(+), 1 deletion(-) + +Bien, una vez confirmado el cambio, vamos a deshacer el cambio con la +orden \`git revert`: + +.. code-block:: console + + $ git revert HEAD --no-edit + [main 817407b] Revert "Ups... este commit está mal" + 1 file changed, 1 insertion(+), 1 deletion(-) + $ git hist + * 817407b 2013-06-16 | Revert "Ups... este commit está mal" (HEAD, main) [Sergio Gómez] + * 5a5d067 2013-06-16 \| Ups... este commit está mal [Sergio Gómez] + * fd4da94 2013-06-16 \| Se añade un comentario al cambio del valor por defecto (tag: v1) [Sergio Gómez] + * 3283e0d 2013-06-16 \| Se añade un parámetro por defecto (tag: v1-beta) [Sergio Gómez] + * efc252e 2013-06-16 \| Parametrización del programa [Sergio Gómez] + * e19f2c1 2013-06-16 \| Creación del proyecto [Sergio Gómez] + +.. graphviz:: + + digraph G { + } + + +Borrar commits de una rama +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +El anterior apartado revierte un commit, pero deja huella en el +historial de cambios. Para hacer que no aparezca hay que usar la orden +``git reset``. + +.. code-block:: console + + $ git reset --hard v1 H + HEAD is now at fd4da94 Se añade un comentario al cambio de valor por defecto + $ git hist + * fd4da94 2013-06-16 | Se añade un comentario al cambio del valor por defecto (HEAD, tag: v1, main) [Sergio Góme + * 3283e0d 2013-06-16 | Se añade un parámetro por defecto (tag: v1-beta) [Sergio Gómez] + * efc252e 2013-06-16 | Parametrización del programa [Sergio Gómez] + * e19f2c1 2013-06-16 | Creación del proyecto [Sergio Gómez] + +.. graphviz:: + + digraph G { + } + +El resto de cambios no se han borrado (aún), simplemente no están +accesibles porque git no sabe como referenciarlos. Si sabemos su hash +podemos acceder aún a ellos. Pasado un tiempo, eventualmente Git tiene +un recolector de basura que los borrará. Se puede evitar etiquetando +el estado final. + +.. warning:: + + La orden ``reset`` es una operación delicada. Debe evitarse si no + se sabe bien lo que se está haciendo, sobre todo cuando se trabaja + en repositorios compartidos, porque podríamos alterar la historia + de cambios lo cual puede provocar problemas de sincronización. + +Modificar un commit +^^^^^^^^^^^^^^^^^^^ + +Esto se usa cuando hemos olvidado añadir un cambio a un commit que +acabamos de realizar. Tenemos nuestro archivo \_hola.php\_ de la +siguiente manera: + +.. code-block:: dylan + +Y lo confirmamos: + +.. code-block:: console + + $ git commit -a -m "Añadido el autor del programa" + [main cf405c1] Añadido el autor del programa + 1 file changed, 1 insertion(+) + +.. graphviz:: + + digraph G { + } + +.. tip:: + + El parámetro ``-a`` hace un ``git add`` antes de hacer + :term:`commit` de todos los archivos modificados o borrados (de los + nuevos no), con lo que nos ahorramos un paso. + +Ahora nos percatamos que se nos ha olvidado poner el correo +electrónico. Así que volvemos a modificar nuestro archivo: + +.. code-block:: dylan + + +Y en esta ocasión usamos ``commit --amend`` que nos permite modificar +el último estado confirmado, sustituyéndolo por el estado actual: + +.. code-block:: console + + $ git add hola.php + $ git commit --amend -m "Añadido el autor del programa y su email" + [main 96a39df] Añadido el autor del programa y su email + 1 file changed, 1 insertion(+) + $ git hist + +.. graphviz:: + + digraph G { + } + +.. warning:: + + Nunca modifiques un :term:`commit` que ya hayas sincronizado con + otro repositorio o que hayas recibido de él. Estarías alterando la + historia de cambios y provocarías problemas de sincronización. + +Moviendo y borrando archivos +---------------------------- + +Mover un archivo a otro directorio con git +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Para mover archivos usaremos la orden ``git mv``: + +.. code-block:: console + + $ mkdir lib + $ git mv hola.php lib + $ git status + # On branch main + # Changes to be committed: + # (use "git reset HEAD ..." to unstage) + # + # renamed: hola.php -> lib/hola.php + # + +Mover y borrar archivos +^^^^^^^^^^^^^^^^^^^^^^^ + +Podíamos haber hecho el paso anterior con la órden del sistema ``mv`` +y el resultado hubiera sido el mismo. Lo siguiente es a modo de +ejemplo y no es necesario que lo ejecutes: + +.. code-block:: console + + $ mkdir lib + $ mv hola.php lib + $ git add lib/hola.php + $ git rm hola.php + +Y, ahora sí, ya podemos guardar los cambios: + +.. code-block:: console + + $ git commit -m "Movido hola.php a lib." + [main 8c2a509] Movido hola.php a lib. + 1 file changed, 0 insertions(+), 0 deletions(-) + rename hola.php => lib/hola.php (100%) + +.. graphviz:: + + digraph G { + } + diff --git a/doc/source/github-avanzado.rst b/doc/source/github-avanzado.rst new file mode 100644 index 0000000..95ce3d6 --- /dev/null +++ b/doc/source/github-avanzado.rst @@ -0,0 +1,271 @@ +.. __github_avanzado: + +Github avanzado +=============== + +Esta sección trata de cómo colaborar con proyectos de terceros. + +.. __clonar_un_repositorio: + +Clonar un repositorio +--------------------- + +Nos vamos a la web del proyecto en el que queremos colaborar. Pulsamos +en el botón de fork y eso creará una copia en nuestro perfil. + +|Barra de información de proyecto| + +Una vez se termine de clonar el repositorio, nos encontraremos con el +espacio de trabajo del mismo: + +- En la parte superior información sobre los commits, ramas, etiquetas, + etc. + +- Justo debajo un explorador de archivos. + +- En la parte derecha un selector para cambiar de contexto entre: + explorador de código, peticiones de colaboración (pull request), + wiki, configuración, etc. + +- Justo abajo a la derecha información sobre como clonar localmente o + descargar un proyecto. + +|Espacio de trabajo| + +Github nos permite clonar localmente un proyecto por tres vías: HTTPS, +SSH y Subversion. Seleccionamos SSH y copiamos el texto que después +añadiremos a la orden ``git clone`` como en la primera línea del +siguiente grupo de órdenes: + +:: + + $ git clone git@github.com:miusuario/miniblog.git + $ cd miniblog + $ composer.phar install + $ php console create-schema + +Lo que hace el código anterior es: + +1. Clona el repositorio localmente + +2. Entramos en la copia + +.. __sincronizar_con_el_repositorio_original: + +Sincronizar con el repositorio original +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Cuando clonamos un repositorio de otro usuario hacemos una copia del +original. Pero esa copia es igual al momento en el que hicimos la copia. +Cuando el repositorio original cambie, que lo hará, nuestro repositorio +no se actualizará solo. ¡Son dos repositorios diferentes! Necesitamos +una manera de poder incorporar los cambios que vaya teniendo el +repositorio original en el nuestro. Para eso crearemos una nueva rama +remota. Por convenio, y como vimos anteriormente, ya existe una rama +remota llamada *origin* que apunta al repositorio de donde clonamos el +proyecto, en este caso apunta a nuestro fork en github: + +:: + + $ git remote show origin + * remote origin + Fetch URL: git@github.com:miusuario/miniblog.git + Push URL: git@github.com:miusuario/miniblog.git + HEAD branch (remote HEAD is ambiguous, may be one of the following): + develop + master + Remote branches: + develop tracked + master tracked + Local branch configured for 'git pull': + master merges with remote master + Local ref configured for 'git push': + master pushes to master (up to date) + +También por convenio, la rama remota que hace referencia al repositorio +original se llama *upstream* y se crea de la siguiente manera: + +:: + + $ git remote add upstream git@github.com:sgomez/miniblog.git + $ git remote show upstream + * remote upstream + Fetch URL: git@github.com:sgomez/miniblog.git + Push URL: git@github.com:sgomez/miniblog.git + HEAD branch: master + Remote branches: + develop new (next fetch will store in remotes/upstream) + master new (next fetch will store in remotes/upstream) + Local ref configured for 'git push': + master pushes to master (local out of date) + +En este caso, la URI debe ser siempre la del proyecto original. Y ahora +para incorporar actualizaciones, usaremos el merge en dos pasos: + +:: + + $ git fetch upstream + $ git merge upstream/master + +Recordemos que *fetch* solo trae los cambios que existan en el +repositorio remoto sin hacer ningún cambio en nuestro repositorio. Es la +orden *merge* la que se encarga de que todo esté sincronizado. En este +caso decimos que queremos fusionar con la rama *master* que está en el +repositorio *upstream*. + +.. __creando_nuevas_funcionalidades: + +Creando nuevas funcionalidades +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Vamos a crear una nueva funcionalidad: vamos a añadir una licencia de +uso. Para ello preferentemente crearemos una nueva rama. + +:: + + $ git checkout -b add-license + $ echo "LICENCIA MIT" > LICESE + # el error es intencionado + $ git add LICESE + $ git commit -m "Archivo de licencia de uso" + +En principio habría que probar que todo funciona bien y entonces +integraremos en la rama *master* de nuestro repositorio y enviamos los +cambios a Github: + +:: + + $ git checkout master + $ git merge add-license --no-ff + $ git branch -d add-license + # Borramos la rama que ya no nos sirve para nada + $ git push --set-upstream origin add-license + # Enviamos la rama a nuestro repositorio origin + +Si volvemos a Github, veremos que nos avisa de que hemos subido una +nueva rama y si queremos crear un pull request. + +|Aviso de nueva rama| + +Pulsamos y entramos en la petición de *Pull Request*. Este es el momento +para revisar cualquier error antes de enviar al dueño del repositorio. +Como vemos hemos cometido uno, nombrando el fichero, si lo correguimos +debemos hacer otro push para ir actualizando la rama. Cuando esté lista +volvemos aquí y continuamos. Hay que dejar una descripción del cambio +que vamos a hacer. + +|Creando un Pull Request| + +Una vez hemos terminado y nos aseguramos que todo está correcto, +pulsamos *Send pull request* y le llegará nuestra petición al dueño del +proyecto. + +|Gestión de un \_Pull Request\_| + +Sin embargo, para esta prueba, no vamos a cambiar el nombre del archivo +y dejaremos el error como está. Así de esta manera al administrador del +proyecto le llegará el *Pull Request* y la lista de cambios. Ahora en +principio, cabría esperar que el administrador aprobara los cambios, +pero podría pasar que nos indicara que cambiemos algo. En ese caso solo +habría que modificar la rama y volverla a enviar. + +:: + + $ git mv LICESE LICENSE + $ git commit -m "Fix: Nombre de archivo LICENSE" + $ git push + +Ahora sí, el administrador puede aprobar la fusión y borrar la rama del +repositorio. El panel de Github permite aceptar los cambios directamente +o informa de como hacer una copia de la rama ofrecida por el usuario +para hacer cambios, como puede verse en la siguiente imagen. + +|Conversación en un \_PullRequest\_| + +Una vez que se han aceptado los cambios, podemos borrar la rama y +actualizar nuestro repositorio con los datos del remoto como hicimos +antes. ¿Por qué actualizar desde el remoto y no desde nuetra rama +*add-license*? Pues porque usualmente el administrador puede haber +modificado los cambios que le hemos propuesto, o incluso una tercera +persona. Recordemos el cariz colaborativo que tiene Github. + +:: + + $ git checkout master + $ git branch -d add-license + # Esto borra la rama local + $ git push origin --delete add-license + # Esto borra la rama remota. También puede hacerse desde la web. + +.. __todo_esto_es_algo_complicado: + +Todo esto es algo complicado… +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sí, lo es, al menos al principio. Git tiene una parte muy sencilla que +es el uso del repositorio local (órdenes tales como add, rm, mv y +commit). El siguiente nivel de complejidad lo componen las órdenes para +trabajar con ramas y fusionarlas (checkout, branch, merge, rebase) y por +último, las que trabajan con repositorios remotos (pull, push, fetch, +remote). Además hay otra serie de órdenes para tener información (diff, +log, status) o hacer operaciones de mantenimiento (fsck, gc). Lo +importante para no perderse en Git, es seguir la siguiente máxima: + +.. important:: + + No avanzar al siguiente nivel de complejidad, hasta no haber + entendido completamente el anterior. + +Muy poco sentido tiene ponernos a crear ramas en github si aún no +entendemos cómo se crean localmente y para que deben usarse. En la parte +de referencias hay varios manuales en línea, incluso tutoriales +interactivos. También hay mucha documentación disponible en Github que +suele venir muy bien explicada. En caso de que tengamos un problema que +no sepamos resolver, una web muy buena es +`StackOverflow `__. Es una web de preguntas y +respuestas para profesionales; es muy difícil que se os plantee una duda +que no haya sido ya preguntada y respondida en esa web. Eso sí, el +inglés es imprescindible. + +.. __último_paso_documentación: + +Último paso, documentación. +--------------------------- + +Github permite crear documentación. En primer lugar, generando un +archivo llamado ``README.md``. También permite crear una web propia para +el proyecto y, además, una wiki. Para marcar el texto, se utiliza un +lenguaje de marcado de texto denominado *Markdown*. En la siguiente web +hay un tutorial interactivo: http://www.markdowntutorial.com/. Como en +principio, no es necesario saber Markdown para poder trabajar con Git o +con Github, no vamos a incidir más en este asunto. + +En el propio GitHub podemos encontrar algunas plantillas que nos sirvan +de referencia. + +Algunos ejemplos: + +- `Plantilla + básica `__ + +- `Plantilla + avanzada `__ + +.. __documentación_del_curso: + +Documentación del curso +~~~~~~~~~~~~~~~~~~~~~~~ + +Esta documentación está hecha en Asciidoc y pasada a PDF gracias a la +herramienta `Asciidoctor `__. + +El material está publicado con licencia `Atribución-NoComercial 4.0 +Internacional (CC BY-NC +4.0) `__ + +.. |Barra de información de proyecto| image:: github-proyect.png +.. |Espacio de trabajo| image:: github-main.png +.. |Aviso de nueva rama| image:: github-pushed.png +.. |Creando un Pull Request| image:: github-mergerequest.png +.. |Gestión de un \_Pull Request\_| image:: github-pullrequest.png +.. |Conversación en un \_PullRequest\_| image:: github-pullconversation.png