Registrando todo

Antes de avanzar hay que revisar nuestro trabajo. Para ello empleamos log.

$ git log
commit b7bbecf3622b94e79ac5e5ff37e2beae9cfb28f6
Author: pateketrueke@gmail.com
Date: Thu Nov 17 16:17:13 2011 -0600

Primer commit; agregue la estructura de archivos


Si aún no recordamos lo último que hicimos la mejor manera de averiguarlo es revisando los cambios por cada commit hecho.

El buen hábito

La utilidad de log es tan solo una vista rápida de los cambios, si no escribimos mensajes de commit que hagan sentido pierde su finalidad y tendremos que buscar otras alternativas. Mi rutina comienza por revisar el repo, luego la rama donde me encuentro, la lista de cambios, los cambios individuales y finalmente las diferencias. Todo un ritual.

$ git status
# On branch develop
nothing to commit (working directory clean)

$ git log
...


Tampoco hay que ser tan estricto, nadie tiene tan mala memoria como yo.

Lo siento git pero, ¿Qué acabo de hacer?

Si deseamos observar los últimos cambios registrados en el commit mas reciente debemos usar show sin argumentos.

...
$ git show

diff --git a/include/funciones.php b/include/funciones.php
index efea0e2..438a62c 100644
--- a/include/funciones.php
+++ b/include/funciones.php
@@ -12,3 +12,30 @@ config(array('clave' => 'valor'));
config(function ($t) {
$t->clave = 'valor';
});
+
+
+/* Contenedor estático de configuraciones */
+
+function config($key = NULL, $val = NULL) {
+ static $bag = array();
+
+ if (func_num_args() === 0) {
+ // Si no hay argumentos devolvemos la configruación
+ return $bag;
+ } elseif (is_string($key)) {
+ if (func_num_args() === 1) {
+ // Si solo hay un argumento devolvemos la opción (getter)
+ return isset($bag[$key]) ? $bag[$key] : NULL;
+ } else {
+ // Si hay dos argumentos asignamos un único valor (setter)
+ $bag[$key] = $val;
+ }
+ }
+
+ // TODO: implementar los specs restantes
+}
+
+
+/* Pruebas */
+
+print_r(config());


La herramienta show puede mostrarnos cualquier cambio hecho, que en realidad es la diferencia del commit especificado contra el anterior. Si deseamos ver la diferencia en otro punto del historial debemos especificar también el hash del commit que buscamos.

$ git show 953de57
commit 953de57c91e88ba5641def12b17ba66041971add
Author: pateketrueke@gmail.com
Date: Thu Nov 17 15:54:55 2011 -0600

+/* Especificaciones */
+
+# asignación sencilla
+config('clave', 'valor');
+
+# asignación múltiple
+config(array('clave' => 'valor'));
+
+# asignación múltiple (fancy)
+config(function ($t) {
+ $t->clave = 'valor';
+});


Observamos precisamente lo que hicimos antes, tan solo las especificaciones.

Las diferencias marcan el cambio

Bien, la utilidad de diferencia es significativamente crucial al momento de hacer commit. Nos detenemos en un punto después de programar intensivamente aquella característica que hará increíble nuestro software pero de pronto no recordamos lo que hemos hecho… ¿les ha pasado algo igual?

En nuestro archivo include/funciones.php tenemos un error de ortografía, nada trivial. Así que simplemente lo corregimos y revisamos nuestros pasos con diff.

$ git diff
diff --git a/include/funciones.php b/include/funciones.php
index 438a62c..cee6be7 100644
--- a/include/funciones.php
+++ b/include/funciones.php
@@ -20,7 +20,7 @@ function config($key = NULL, $val = NULL) {
static $bag = array();

if (func_num_args() === 0) {
- // Si no hay argumentos devolvemos la configruación
+ // Si no hay argumentos devolvemos la configuración
return $bag;
} elseif (is_string($key)) {
if (func_num_args() === 1) {


Con esto ya nos damos una idea de lo que sucedió, así que simplemente lo indicamos en nuestro mensaje de commit y guardamos los cambios para conservar la referencia de que tan malos solos en gramática.

$ git commit -am "Error ortografico hombre, tu tranqui"
[develop d4ad04e] Error ortografico hombre, tu tranqui
1 files changed, 1 insertions(+), 1 deletions(-)


Al igual que show, la utilidad diff acepta distintos tipos de argumentos. Siempre podremos comparar un commit contra cualquier otro sin importar si son consecutivos o no. ¡Haz la prueba!

$ git diff 14d8578 b7bbecf
...


Resumen

• Cada commit nos abre la posibilidad de revisar dicho cambio cuando se nos
  de la gana, al inspeccionar un bug, analizar las mejoras del software, calcular el tiempo de trabajo invertido, etc.
• Revisar nuestros commits nos permite conocer mejor el software que desarrollamos, ayuda a reflexionar sobre la calidad del mismo y también a vislumbrar el rumbo de nuestros proyectos entre otras cosas.
• Un registro de cambios eficiente se fundamenta no solo en los cambios de código, sino también en los humanos que revisan el código.

De verdad que es genial leer código bien desarrollado. O bien explicado.

No por nada GitHub es considerado, eso pienso, una representación colectiva de arte moderno.

Repositorio: Mi libreria

Alvaro Cabrera para Maestros del Web.
Agrega tu comentario | Enlace permanente al artículo

Síguenos en: @maestros | Fan page

Lo ideal es que siempre trabajemos la versión estable de nuestros proyectos en la rama master que es el estándar bajo el ecosistema Gitero. Es posible usar otro nombre de rama pero como un amigo mío dijo “las convenciones existen por algo, si no las sigues es síntoma de que un proyecto OpenSource fracase.

Preparativos

La rama que vamos a crear y utilizar intensivamente en el desarrollo es conocida como develop, a partir de esa rama podemos desprender otras ramas para desarrollar otras características de nuestro software sin afectar el desarrollo principal, ni mucho menos la versión estable del repositorio.

Para mostrar las ramas existentes localmente ejecutamos:

$ git branch
* master

Entonces creamos la rama develop:

$ git branch develop
$ git branch
develop
* master


El asterisco al inicio del nombre de una rama nos indica que estamos actualmente en dicha rama, para cambiar entre ramas debemos usar checkout:

$ git checkout develop
Switched to branch 'develop'

Bien, ahora si podemos comenzar el desarrollo de nuestro proyecto desde la rama develop. ¿No les parece genial?

Ramas inferiores

Es recomendable crear ramas cuando los cambios que llevemos a cabo tenga una relación entre sí, digamos, si vamos a editar tan solo nuestros archivos en include/ sería conveniente crear una rama exclusivamente para los cambios realizados ahí.

No es obligatorio, pero de verdad mas adelante descubrirán el poder que existe al separar nuestros cambios sin la posibilidad de afectar a otros archivos.

Así pues, vamos a crear una rama llamada include-specs a partir de nuestra rama actual (develop) donde describiremos lo que haga nuestro software:

$ git checkout -b include-specs
Switched to a new branch 'include-specs'


Este sería el contenido de nuestro archivo include/funciones.php:

<?php
/* Especificaciones */
# asignación sencilla
config('clave', 'valor');
# asignación múltiple
config(array('clave' => 'valor'));
# asignación múltiple (fancy)
config(function ($t) {
$t->clave = 'valor';
});


La bandera -b de checkout nos permite crear una nueva rama basada en la rama actual y cambiar a ella, usualmente es un atajo que nos ahorra el trabajo de hacer lo siguiente:

$ git branch include-specs
$ git checkout include-specs
Switched to a new branch 'include-specs'

Revisamos los cambios con status:

$ git status
# On branch include-specs
# Changes not staged for commit:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: include/funciones.php
#
no changes added to commit (use "git add" and/or "git commit -a")

Hacemos commit y revisamos cambios de nuevo:

$ git commit -am "Especificaciones para config()"
1 files changed, 13 insertions(+), 0 deletions(-)
$ git status
# On branch include-specs
nothing to commit (working directory clean)

Más cambios, por favor

Excelente, ya sabemos crear ramas y realizar cambios que solo permanezcan ahí, para comprobarlo cambiamos a la rama develop y revisamos el contenido del archivo que modificamos en include-specs:

$ git checkout develop
$ cat include/funciones.php


No hay nada, y eso es bueno, quiere decir que vamos bien. Ahora necesitamos comenzar a implementar la función config() para posteriormente hacer pruebas y si todo funciona como esperamos combinamos el resultado a nuestra rama develop.

Cambiamos de nuevo a la rama include-specs y agregamos lo siguiente a nuestro script de funciones:

/* Contenedor estático de configuraciones */

if (func_num_args() === 0) {
// Si no hay argumentos devolvemos la configuración
return $bag;
} elseif (is_string($key)) {
if (func_num_args() === 1) {
// Si solo hay un argumento devolvemos la opción (getter)
return isset($bag[$key]) ? $bag[$key] : NULL;
} else {
// Si hay dos argumentos asignamos un único valor (setter)
$bag[$key] = $val;
}
}
// TODO: implementar los specs restantes
}
/* Pruebas */
print_r(config());

Verificamos la sintaxis y ejecutamos el script desde la consola:

$ php -l include/funciones.php
No syntax errors detected in include/funciones.php
$ php include/funciones.php
Array
(
[clave] => valor
)

El script funciona, no en su totalidad, pero cumple al menos una de las especificaciones que contemplamos en nuestro script inicialmente.

Si no queremos perder los cambios que llevamos hasta este punto vamos a hacer commit y no más.

$ git commit -am "El primer spec funciona, y muy bien"
1 files changed, 27 insertions(+), 0 deletions(-)


Las banderas -am nos permiten agregar automáticamente los archivos modificados y establecer un mensaje para el commit.

Integrando los cambios, gracias

Hemos creado ya la rama develop, una auxiliar include-specs para separar los cambios en porciones y ya verificamos que nuestro código cumple las expectativas que nos planteamos. Entonces ya es tiempo de formalizar todo esto y llevar los cambios hacía la rama de desarrollo, hay que utilizar merge para finalizar nuestro trabajo del día de hoy:

$ git checkout develop
Switched to branch 'develop'
$ git merge include-specs
Updating 14d8578..cfdd6ae
Fast-forward
include/funciones.php | 40 ++++++++++++++++++++++++++++++++++++++++
1 files changed, 40 insertions(+), 0 deletions(-)


Y ahí tenemos, nuestros cambios realizados en la rama auxiliar los hemos integrado a la rama oficial de desarrollo.

Integrar cambios es lo más sencillo del mundo si mantenemos la calma y trabajamos en orden, despacio y por partes, si nos ponemos a editar y mover mucho código en una sola sesión de commits cuando intentemos mezclar los cambios nos vamos a encontrar conflictos. Tampoco son complicados de solucionar cuando hablamos de un solo archivo, pero bueno, creo que ya se darán una mejor idea cuando toquemos el tema.

¡Buen trabajo!

Es importante notar que no trabajamos directamente sobre la rama develop, mucho menos aún con la rama master. Aunque hay quienes les gusta arriesgar su trabajo poniendo en riesgo la integridad y estabilidad de su software pero no es conveniente hacer todo en un solo sitio, para eso están diseñadas las ramas y efectivamente funcionan. No hay que ser extremista tampoco, pero de verdad, un poco de sentido común basta.

Aunque por ahora no hemos terminado de usar la rama include-specs vamos a suponer que ya no sirve, pues nuestro código se encuentra estable y necesitamos eliminar referencias innecesarias. Veamos lo siguiente para ejemplificar:

$ git branch experimental
$ git branch -d experimental
Deleted branch experimental (was cfdd6ae).


Resumen

• Así como un commit debe ser considerado atómico, una rama debe tratarse como un conjunto de dichos átomos, es decir, una forma de agrupar cambios en común y no más.
• Es sencillo pensar en ramas cuando agregamos alguna funcionalidad a nuestro software, de hecho es la manera sugerida para su utilización.

Por ahora no vamos a profundizar a detalle sobre banderas y opciones de cada comando así como ningún tipo de técnica avanzada. La idea de estos ejercicios es mostrar el flujo de trabajo mas sencillo posible que se puede llevar a cabo con Git. Hay escenarios mas complejos y cuando se trabaja con más de una persona pueden suceder cosas complicadas, pero no hay que temer, Git es el salvador de nuestro código.

Github: Mi librería.

Alvaro Cabrera para Maestros del Web.
Agrega tu comentario | Enlace permanente al artículo

Síguenos en: @maestros | Fan page

Hoy iniciamos una serie de artículos en donde nos concentraremos en conocer el flujo de trabajo (workflow) básico para llevar a cabo el versionado de nuestros proyectos.

El proyecto de ejemplo se puede consultar directamente en su repositorio de GitHub, en el cual colocaré un tag por cada articulo, para que sean fácil de reconocer los avances.

¿Como lo consigo?

Asumo que ya tenemos instalado Git en nuestro sistema, es fácil conseguirlo si tenemos alguna distribución Linux u OS X, cualquier sistema basado en *nix funciona excelente. Después de instalar Git hay que configurar nuestros datos básicos:

$ git config --global user.name "Mi nombre"
$ git config --global user.email "mi@correo.com"

Considero que los primeros pasos que debemos concretar tienen que ver en la creación y gestión de un repositorio de forma local, a nivel bastante básico veremos como iniciar nuestros repositorios y registrar cambios en el historial de Git.

Por si mismo, Git es una herramienta con una curva de aprendizaje pronunciada, si no disciplinamos nuestro flujo de trabajo a la par de Git es muy posible que nos encontremos en problemas casi todo el tiempo. No hay que temer, si llevamos un orden y aprendemos a registrar nuestros cambios casi de forma atómica es poco probable que ocurra algo que lamentar.

Creando nuestro repositorio

Cualquier carpeta de nuestro sistema puede ser un contenedor o repositorio para Git, en dicho lugar se establecerá la configuración e historial bajo una carpeta nombrada .git que se encuentra oculta.

Para crear un repositorio no es necesario empezar desde cero con nuestro proyecto, de hecho podemos iniciar uno aún cuando ya tenemos nuestro código en estado avanzado. Por ejemplo, tenemos la estructura de un sistema o librería sencilla:

/proyectos/mi-libreria
/proyectos/mi-libreria/include
/proyectos/mi-libreria/include/sistema.class.php
/proyectos/mi-libreria/include/funciones.php
/proyectos/mi-libreria/index.php


Solo hay que ubicarnos en la carpeta y ejecutar git init para crear el repositorio:

$ cd /proyectos/mi-libreria
$ git init

Initialized empty Git repository in /proyectos/mi-libreria/.git/


Registrar y guardar archivos

Cada repositorio guarda un historial de los cambios que hemos ido realizando en nuestro proyecto, ejecutando git status podemos verificar los cambios hechos en el estado actual:

$ git status

# On branch master
#
# Initial commit
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# include/
# index.php
nothing added to commit but untracked files present (use "git add" to track)


En el ejemplo notamos que nos hace falta registrar los archivos contenidos en la raíz de nuestro proyecto, ahora vamos a agregarlos:

$ git add .
$ git status

# On branch master
#
# Initial commit
#
# Changes to be committed:
# (use "git rm --cached <file>..." to unstage)
#
# new file: include/funciones.php
# new file: include/sistema.class.php
# new file: index.php
#


He usado git add . pues el punto indica la ruta actual y, por defecto, Git agrega recursivamente al emplear ésta instrucción con una carpeta como argumento. Desde luego es posible agregar archivos individualmente con solo especificar la ruta relativa con relación a la raíz del repositorio, por ejemplo:

$ git add include/funciones.php


Finalmente debemos dar por hechos los cambios que llevamos en el repositorio, entonces ejecutamos git commit para confirmarlo:

$ git commit -m "Primer commit; agregue la estructura de archivos"

[master (root-commit) 0034116] Primer commit; agregue la estructura de archivos
3 files changed, 3 insertions(+), 0 deletions(-)
create mode 100644 include/funciones.php
create mode 100644 include/sistema.class.php
create mode 100644 index.php


Verificamos que todo esté en orden con git status de nuevo:

$ git status

# On branch master
nothing to commit (working directory clean)


Supongamos que la frecuencia de los cambios que realizamos a nuestro código determina la cantidad de commits que podemos efectuar en el repositorio. Lo ideal sería que por cada nuevo cambio significativo en el código o estructura de archivos, registremos lo que hicimos agregando los archivos afectados con una descripción puntual, breve y clara de lo realizado.

Si por ejemplo hay que mover un archivo de lugar, o simplemente le cambiamos de nombre debemos asegurarnos de tener el historial de cambios limpio antes de proceder.

Resumen

• Un repositorio en Git es un registro de cambios hechos a través del tiempo que sirve para llevar un orden progresivo con respecto al desarrollo de algún proyecto, básicamente código fuente y documentos.

• Cada archivo agregado, renombrado, editado o eliminado debe ser registrado para no perder el orden de los cambios en nuestro proyecto; pensar en un cambio a la vez es fundamental.

En los siguientes artículos iremos viendo estos dos puntos a detalle, sobre todo el manejo de ramas a nivel básico usando branch, checkout, rebase y merge para lograr un flujo de trabajo mas flexible así como diversas técnicas y recomendaciones para un registro de cambios mas efectivo con commit, cherry-pick, reset, diff, show y log.

Una vez tengamos dominado el flujo de trabajo básico de manera local podremos continuar con la obtención, publicación y actualización de repositorios con remote, fetch, pull y push.

Github: Mi libreria

Alvaro Cabrera para Maestros del Web.
Agrega tu comentario | Enlace permanente al artículo

Síguenos en: @maestros | Fan page