maintaining.asc

Mantenir un Projecte

A més de saber com contribuir de manera efectiva a un projecte, probablement també necessitareu saber com mantenir-ne un. Això pot consistir en acceptar i aplicar parxos generats mitjançant format-patch i enviats per correu electrònic, o integrar canvis en branques remotes per a repositoris que heu afegit com a remots al vostre projecte. Ja sigui que mantingueu un repositori canònic o vulgueu ajudar verificant o aprovant parxos, heu de saber com acceptar la feina de la manera més clara per a altres contribuïdors i sostenible per a vosaltres a llarg termini.

Treballar en Branques de Tema

Quan esteu pensant en integrar nova feina, generalment és una bona idea provar-la en una branca de tema: una branca temporal creada específicament per provar aquesta nova feina. D’aquesta manera, és fàcil ajustar un parxo individualment i deixar-lo si no funciona fins que tingueu temps per tornar-hi. Si creeu un nom de branca senzill basat en el tema de la feina que aneu a provar, com ruby_client o alguna cosa similarment descriptiva, podeu recordar-lo fàcilment si heu d’abandonar-lo per una estona i tornar-hi més tard. El mantenedor del projecte Git sol espaiar aquestes branques també, com sc/ruby_client, on sc és curt per a la persona que va contribuir la feina. Com recordareu, podeu crear la branca basada en la vostra branca master així:

$ git branch sc/ruby_client master

O, si voleu canviar-hi immediatament, podeu utilitzar l’opció checkout -b:

$ git checkout -b sc/ruby_client master

Ara esteu preparats per afegir la feina contribuïda que heu rebut a aquesta branca de tema i determinar si voleu fusionar-la a les vostres branques de llarg termini.

Aplicar Parxos des de Correu Electrònic

Si rebeu un parxo per correu electrònic que heu d’integrar al vostre projecte, heu d’aplicar el parxo a la vostra branca de tema per avaluar-lo. Hi ha dues maneres d’aplicar un parxo enviat per correu electrònic: amb git apply o amb git am.

Aplicar un Parxo amb apply

Si heu rebut el parxo d’algú que l’ha generat amb git diff o alguna variant de l’ordre diff d’Unix (el qual no es recomana; vegeu la següent secció), podeu aplicar-lo amb l’ordre git apply. Suposant que heu desat el parxo a /tmp/patch-ruby-client.patch, podeu aplicar el parxo així:

$ git apply /tmp/patch-ruby-client.patch

Això modifica els fitxers al vostre directori de treball. És gairebé idèntic a executar un ordre patch -p1 per aplicar el parxo, tot i que és més paranoic i accepta menys coincidències difuses que patch. També gestiona afegits, eliminacions i canvis de nom de fitxers si es descriuen al format git diff, el qual patch no fa. Finalment, git apply és un model de “aplica-ho tot o avorta-ho tot” on o s’aplica tot o res, mentre que patch pot aplicar parcialment fitxers de parxo, deixant el vostre directori de treball en un estat estrany. git apply és en general molt més conservador que patch. No crearà un commit per a vosaltres: després d’executar-lo, heu de preparar i fer commit dels canvis introduïts manualment.

També podeu utilitzar git apply per veure si un parxo s’aplica netament abans d’intentar aplicar-lo realment: podeu executar git apply --check amb el parxo:

$ git apply --check 0001-see-if-this-helps-the-gem.patch
error: patch failed: ticgit.gemspec:1
error: ticgit.gemspec: patch does not apply

Si no hi ha sortida, llavors el parxo s’hauria d’aplicar netament. Aquest ordre també surt amb un estat no zero si la comprovació falla, així que podeu utilitzar-lo en scripts si voleu.

Aplicar un Parxo amb am

Si el contribuïdor és un usuari de Git i ha estat prou amable per utilitzar l’ordre format-patch per generar el seu parxo, llavors la vostra feina és més fàcil perquè el parxo conté informació de l’autor i un missatge de commit per a vosaltres. Si podeu, animeu els vostres contribuïdors a utilitzar format-patch en lloc de diff per generar parxos per a vosaltres. Només haureu d’utilitzar git apply per a parxos heredats i coses així.

Per aplicar un parxo generat per format-patch, utilitzeu git am (l’ordre es diu am ja que s’utilitza per “aplicar una sèrie de parxos des d’una safata de correu”). Tècnicament, git am està construït per llegir un fitxer mbox, que és un format de text pla senzill per emmagatzemar un o més missatges de correu electrònic en un fitxer de text. S’assembla a alguna cosa així:

From 330090432754092d704da8e76ca5c05c198e71a8 Mon Sep 17 00:00:00 2001
From: Jessica Smith <jessica@example.com>
Date: Sun, 6 Apr 2008 10:17:23 -0700
Subject: [PATCH 1/2] Add limit to log function

Limit log functionality to the first 20

Això és l’inici de la sortida de l’ordre git format-patch que vau veure a la secció anterior; també representa un format de correu electrònic mbox vàlid. Si algú us ha enviat el parxo correctament utilitzant git send-email, i el descarregueu en format mbox, llavors podeu apuntar git am a aquest fitxer mbox, i començarà a aplicar tots els parxos que veu. Si executeu un client de correu que pot desar diversos correus electrònics en format mbox, podeu desar tota una sèrie de parxos en un fitxer i després utilitzar git am per aplicar-los un a un.

No obstant això, si algú ha pujat un fitxer de parxo generat mitjançant git format-patch a un sistema de tiquets o alguna cosa similar, podeu desar el fitxer localment i després passar aquest fitxer desat al disc a git am per aplicar-lo:

$ git am 0001-limit-log-function.patch
Applying: Add limit to log function

Podeu veure que s’ha aplicat netament i ha creat automàticament el nou commit per a vosaltres. La informació de l’autor es pren de les capçaleres From i Date del correu electrònic, i el missatge del commit es pren de l'`Subject` i el cos (abans del parxo) del correu electrònic. Per exemple, si aquest parxo s’aplicava des de l’exemple mbox anterior, el commit generat semblaria alguna cosa així:

$ git log --pretty=fuller -1
commit 6c5e70b984a60b3cecd395edd5b48a7575bf58e0
Author:     Jessica Smith <jessica@example.com>
AuthorDate: Sun Apr 6 10:17:23 2008 -0700
Commit:     Scott Chacon <schacon@gmail.com>
CommitDate: Thu Apr 9 09:19:06 2009 -0700

   Add limit to log function

   Limit log functionality to the first 20

La informació de Commit indica la persona que va aplicar el parxo i quan es va aplicar. La informació d'`Author` és l’individu que originalment va crear el parxo i quan es va crear originalment.

Però és possible que el parxo no s’apliqui netament. Potser la vostra branca principal ha divergit massa de la branca de la qual es va construir el parxo, o el parxo depèn d’un altre parxo que encara no heu aplicat. En aquest cas, el procés git am fallarà i us demanarà què voleu fer:

$ git am 0001-see-if-this-helps-the-gem.patch
Applying: See if this helps the gem
error: patch failed: ticgit.gemspec:1
error: ticgit.gemspec: patch does not apply
Patch failed at 0001.
When you have resolved this problem run "git am --resolved".
If you would prefer to skip this patch, instead run "git am --skip".
To restore the original branch and stop patching run "git am --abort".

Aquest ordre posa marcadors de conflicte en qualsevol fitxer amb el qual tingui problemes, molt semblant a una operació de fusió o rebase conflictiva. Resoleu aquest problema de manera similar: editeu el fitxer per resoldre el conflicte, prepareu el nou fitxer, i després executeu git am --resolved per continuar amb el següent parxo:

$ (fix the file)
$ git add ticgit.gemspec
$ git am --resolved
Applying: See if this helps the gem

Si voleu que Git intenti resoldre el conflicte una mica més intel·ligentment, podeu passar-li l’opció -3, que fa que Git intenti una fusió de tres vies. Aquesta opció no està activada per defecte perquè no funciona si el commit del qual diu el parxo que es basa no està al vostre repositori. Si teniu aquest commit: si el parxo es basava en un commit públic, llavors l’opció -3 generalment és molt més intel·ligent a l’hora d’aplicar un parxo conflictiu:

$ git am -3 0001-see-if-this-helps-the-gem.patch
Applying: See if this helps the gem
error: patch failed: ticgit.gemspec:1
error: ticgit.gemspec: patch does not apply
Using index info to reconstruct a base tree...
Falling back to patching base and 3-way merge...
No changes -- Patch already applied.

En aquest cas, sense l’opció -3 el parxo hauria estat considerat com un conflicte. Com que s’ha utilitzat l’opció -3, el parxo s’ha aplicat netament.

Si esteu aplicant una sèrie de parxos des d’un mbox, també podeu executar l’ordre am en mode interactiu, que s’atura a cada parxo que troba i us demana si voleu aplicar-lo:

$ git am -3 -i mbox
Commit Body is:
--------------------------
See if this helps the gem
--------------------------
Apply? [y]es/[n]o/[e]dit/[v]iew patch/[a]ccept all

Això és útil si teniu una sèrie de parxos desats, perquè podeu veure el parxo primer si no recordeu què és, o no aplicar el parxo si ja ho heu fet.

Quan tots els parxos per al vostre tema s’han aplicat i s’han fet commit a la vostra branca, podeu triar si i com voleu integrar-los a una branca de més llarg termini.

Comprovar Branques Remotes

Si la vostra contribució ve d’un usuari de Git que ha configurat el seu propi repositori, ha fet push d’una sèrie de canvis i després us ha enviat la URL al repositori i el nom de la branca remota on es troben els canvis, podeu afegir-los com a remot i fer fusions localment.

Per exemple, si Jessica us envia un correu electrònic dient que té una gran nova funció a la branca ruby-client del seu repositori, podeu provar-la afegint el remot i comprovant aquesta branca localment:

$ git remote add jessica https://github.com/jessica/myproject.git
$ git fetch jessica
$ git checkout -b rubyclient jessica/ruby-client

Si us torna a enviar un correu electrònic més tard amb una altra branca que conté una altra gran funció, podeu fer directament fetch i checkout perquè ja teniu configurat el remot.

Això és especialment útil si esteu treballant amb una persona de manera consistent. Si algú només té un únic parxo per contribuir de tant en tant, llavors acceptar-lo per correu electrònic pot ser menys consumidor de temps que requerir que tots executin el seu propi servidor i haver d’afegir i eliminar remots contínuament per obtenir uns quants parxos. També és poc probable que vulgueu tenir centenars de remots, cadascun per a algú que contribueixi només un o dos parxos. No obstant això, els scripts i els serveis allotjats poden fer això més fàcil: depèn en gran manera de com desenvolupeu i com desenvolupen els vostres contribuïdors.

L’altre avantatge d’aquest enfocament és que també obteniu l’historial dels commits. Tot i que podeu tenir problemes de fusió legítims, sabeu on a la vostra història es basa la seva feina: una fusió de tres vies adequada és la predeterminada en lloc d’haver de proporcionar un -3 i esperar que el parxo es generi a partir d’un commit públic al qual teniu accés.

Si no esteu treballant amb una persona de manera consistent però encara voleu fer pull d’ells d’aquesta manera, podeu proporcionar la URL del repositori remot a l’ordre git pull. Això fa un pull d’una sola vegada i no desa la URL com a referència remota:

$ git pull https://github.com/onetimeguy/project
From https://github.com/onetimeguy/project
 * branch            HEAD       -> FETCH_HEAD
Merge made by the 'recursive' strategy.

Determinar Què S’ha Introduït

Ara teniu una branca de tema que conté feina contribuïda. En aquest punt, podeu determinar què us agradaria fer amb ella. Aquesta secció revisa un parell d’ordres perquè pugueu veure com podeu utilitzar-los per revisar exactament què introduireu si fusionau això a la vostra branca principal.

Sovint és útil obtenir una revisió de tots els commits que estan a aquesta branca però que no estan a la vostra branca master. Podeu excloure els commits a la branca master afegint l’opció --not abans del nom de la branca. Això fa el mateix que el format master..contrib que vam utilitzar abans. Per exemple, si el vostre contribuïdor us envia dos parxos i creeu una branca anomenada contrib i apliqueu aquests parxos allà, podeu executar això:

$ git log contrib --not master
commit 5b6235bd297351589efc4d73316f0a68d484f118
Author: Scott Chacon <schacon@gmail.com>
Date:   Fri Oct 24 09:53:59 2008 -0700

    See if this helps the gem

commit 7482e0d16d04bea79d0dba8988cc78df655f16a0
Author: Scott Chacon <schacon@gmail.com>
Date:   Mon Oct 22 19:38:36 2008 -0700

    Update gemspec to hopefully work better

Per veure quins canvis introdueix cada commit, recordeu que podeu passar l’opció -p a git log i s’afegirà el diff introduït a cada commit.

Per veure un diff complet del que passaria si fusionéssiu aquesta branca de tema amb una altra branca, potser heu d’utilitzar un truc estrany per obtenir els resultats correctes. Potser penseu executar això:

$ git diff master

Aquest ordre us dona un diff, però pot ser enganyós. Si la vostra branca master ha avançat des que vau crear la branca de tema, llavors obtindreu resultats aparentment estranys. Això passa perquè Git compara directament les instantànies de l’últim commit de la branca de tema en la qual esteu i l’instantània de l’últim commit a la branca master. Per exemple, si heu afegit una línia en un fitxer a la branca master, una comparació directa de les instantànies semblarà que la branca de tema eliminarà aquesta línia.

Si master és un avantpassat directe de la vostra branca de tema, això no és un problema; però si les dues històries han divergit, el diff semblarà que esteu afegint tota la nova feina a la vostra branca de tema i eliminant tot el que és únic a la branca master.

El que realment voleu veure són els canvis afegits a la branca de tema: la feina que introduireu si fusionau aquesta branca amb master. Ho feu fent que Git compari l’últim commit a la vostra branca de tema amb el primer avantpassat comú que té amb la branca master.

Tècnicament, podeu fer això determinant explícitament l’avantpassat comú i després executant el vostre diff sobre ell:

$ git merge-base contrib master
36c7dba2c95e6bbb78dfa822519ecfec6e1ca649
$ git diff 36c7db

o, més concisament:

$ git diff $(git merge-base contrib master)

No obstant això, cap d’aquests és especialment convenient, així que Git proporciona una altra abreviatura per fer el mateix: la sintaxi de triple punt. En el context de l’ordre git diff, podeu posar tres punts després d’una altra branca per fer un diff entre l’últim commit de la branca en la qual esteu i el seu avantpassat comú amb una altra branca:

$ git diff master...contrib

Aquest ordre us mostra només la feina que la vostra branca de tema actual ha introduït des del seu avantpassat comú amb master. Aquesta és una sintaxi molt útil per recordar.

Integrar Feina Contribuïda

Quan tota la feina a la vostra branca de tema està llesta per ser integrada a una branca de més llarg termini, la pregunta és com fer-ho. A més, quin flux de treball general voleu utilitzar per mantenir el vostre projecte? Teniu diverses opcions, així que tractarem algunes d’elles.

Fluxos de Treball de Fusió

Un flux de treball bàsic és simplement fusionar tota aquesta feina directament a la vostra branca master. En aquest escenari, teniu una branca master que conté codi bàsicament estable. Quan teniu feina a una branca de tema que penseu que heu completat, o feina que algú altre ha contribuït i heu verificat, la fusionau a la vostra branca master, elimineu aquesta branca de tema acabada de fusionar, i repetiu.

Per exemple, si tenim un repositori amb feina a dues branques anomenades ruby_client i php_client que sembla Historial amb diverses branques de tema, i fusionem ruby_client seguit de php_client, la vostra història acabarà semblant a Després d’una fusió de branca de tema.

Figure 1. Historial amb diverses branques de tema

Figure 2. Després d’una fusió de branca de tema

Això és probablement el flux de treball més senzill, però pot ser problemàtic si esteu tractant amb projectes més grans o més estables on voleu ser molt cuidadosos amb el que introduïu.

Si teniu un projecte més important, potser voldreu utilitzar un cicle de fusió de dues fases. En aquest escenari, teniu dues branques de llarg termini, master i develop, on determineu que master s’actualitza només quan es talla una versió molt estable i tota la nova feina s’integra a la branca develop. Feu push de totes dues branques al repositori públic regularment. Cada vegada que teniu una nova branca de tema per fusionar (Antes d’una fusió de branca de tema), la fusionau a develop (Després d’una fusió de branca de tema); llavors, quan etiqueteu una versió, feu un fast-forward de master a on es troba ara la branca develop estable (Després d’una versió del projecte).

Figure 3. Antes d’una fusió de branca de tema

Figure 4. Després d’una fusió de branca de tema

Figure 5. Després d’una versió del projecte

D’aquesta manera, quan la gent clona el repositori del vostre projecte, poden fer checkout de master per construir l’última versió estable i mantenir-se al dia fàcilment, o poden fer checkout de develop, que és el contingut més innovador. També podeu estendre aquest concepte tenint una branca integrate on tota la feina es fusiona junta. Llavors, quan la base de codi a aquesta branca és estable i passa les proves, la fusionau a una branca develop; i quan aquesta ha demostrat ser estable durant una estona, feu un fast-forward de la vostra branca master.

Fluxos de Treball de Gran Fusió

El projecte Git té quatre branques de llarg termini: master, next, i seen (abans 'pu' — actualitzacions proposades) per a nova feina, i maint per a retroports de manteniment. Quan es presenta nova feina pels contribuïdors, es recull en branques de tema al repositori del mantenedor d’una manera similar al que hem descrit (vegeu Gestionar una sèrie complexa de branques de tema contribuïdes en paral·lel). En aquest punt, els temes s’avaluen per determinar si són segurs i llests per al consum o si necessiten més feina. Si són segurs, es fusionen a next, i aquesta branca es fa push perquè tots puguin provar els temes integrats junts.

Figure 6. Gestionar una sèrie complexa de branques de tema contribuïdes en paral·lel

Si els temes encara necessiten feina, es fusionen a seen en lloc d’això. Quan es determina que són totalment estables, els temes es tornen a fusionar a master. Les branques next i seen es tornen a reconstruir des de master. Això significa que master gairebé sempre avança, next es rebaseja ocasionalment, i seen es rebaseja encara més sovint:

Figure 7. Fusionar branques de tema contribuïdes a branques d’integració de llarg termini

El projecte Git també té una branca maint que es bifurca des de l’última versió per proporcionar parxos retroportats en cas que es requereixi una versió de manteniment. Així, quan cloneu el repositori de Git, teniu quatre branques que podeu comprovar per avaluar el projecte en diferents etapes de desenvolupament, depenent de com de innovador vulgueu ser o com vulgueu contribuir; i el mantenedor té un flux de treball estructurat per ajudar-los a avaluar noves contribucions. El flux de treball del projecte Git està especialitzat. Per entendre això clarament, podeu consultar la guia del mantenedor de Git a Guia del Mantenedor de Git.

Fluxos de Treball de Rebase i Cherry-Picking

Altres mantenedors prefereixen rebasejar o fer cherry-pick de la feina contribuïda sobre la seva branca master, en lloc de fusionar-la, per mantenir una història principalment lineal. Quan teniu feina a una branca de tema i heu determinat que voleu integrar-la, us moureu a aquesta branca i executeu l’ordre de rebase per reconstruir els canvis sobre la vostra branca master actual (o develop, etc.). Si això funciona bé, podeu fer un fast-forward de la vostra branca master, i acabareu amb una història de projecte lineal.

L’altra manera de moure la feina introduïda d’una branca a una altra és fer-ne cherry-pick. Un cherry-pick a Git és com un rebase per a un únic commit. Prèn el parxo que es va introduir en un commit i intenta tornar-lo a aplicar a la branca en la qual esteu actualment. Això és útil si teniu una sèrie de commits a una branca de tema i voleu integrar-ne només un, o si només teniu un commit a una branca de tema i preferiu fer-ne cherry-pick en lloc d’executar rebase. Per exemple, suposem que teniu un projecte que sembla això:

Figure 8. Exemple d’historial abans d’un cherry-pick

Si voleu treure el commit e43a6 a la vostra branca master, podeu executar:

$ git cherry-pick e43a6
Finished one cherry-pick.
[master]: created a0a41a9: "More friendly message when locking the index fails."
 3 files changed, 17 insertions(+), 3 deletions(-)

Això treu el mateix canvi introduït a e43a6, però obteniu un nou valor SHA-1 de commit, perquè la data d’aplicació és diferent. Ara el vostre historial sembla això:

Figure 9. Historial després de fer cherry-pick d’un commit a una branca de tema

Ara podeu eliminar la vostra branca de tema i deixar els commits que no volíeu treure.

Rerere

Si esteu fent moltes fusions i rebasejos, o esteu mantenint una branca de tema de llarg termini, Git té una funció anomenada “rerere” que us pot ajudar.

Rerere significa “reutilitzar resolució registrada”: és una manera d’abreujar la resolució manual de conflictes. Quan rerere està habilitat, Git mantindrà un conjunt d’imatges pre- i post- de fusions reeixides, i si nota que hi ha un conflicte que sembla exactament com un que ja heu corregit, simplement utilitzarà la correcció de l’última vegada, sense molestar-vos amb això.

Aquesta funció ve en dues parts: una configuració i un ordre. La configuració és rerere.enabled, i és prou útil per posar-la a la vostra configuració global:

$ git config --global rerere.enabled true

Ara, sempre que feu una fusió que resol conflictes, la resolució es registrarà a la memòria cau en cas que la necessiteu en el futur.

Si ho necessiteu, podeu interactuar amb la memòria cau de rerere utilitzant l’ordre git rerere. Quan s’invoca sol, Git comprova la seva base de dades de resolucions i intenta trobar una coincidència amb qualsevol conflicte de fusió actual i resoldre’ls (tot i que això es fa automàticament si rerere.enabled està establert a true). També hi ha subordres per veure què es registrarà, per esborrar una resolució específica de la memòria cau, i per netejar tota la memòria cau. Tractarem rerere amb més detall a ch07-git-tools.asc.

Etiquetar les Vostres Versions

Quan heu decidit tallar una versió, probablement voldreu assignar una etiqueta perquè pugueu recrear aquesta versió en qualsevol moment en endavant. Podeu crear una nova etiqueta com es va discutir a ch02-git-basics-chapter.asc. Si decideu signar l’etiqueta com a mantenedor, l’etiquetatge pot semblar alguna cosa així:

$ git tag -s v1.5 -m 'my signed 1.5 tag'
You need a passphrase to unlock the secret key for
user: "Scott Chacon <schacon@gmail.com>"
1024-bit DSA key, ID F721C45A, created 2009-02-09

Si signeu les vostres etiquetes, podeu tenir el problema de distribuir la clau pública PGP utilitzada per signar les vostres etiquetes. El mantenedor del projecte Git ha resolt aquest problema incloent la seva clau pública com a blob al repositori i després afegint una etiqueta que apunta directament a aquest contingut. Per fer això, podeu determinar quina clau voleu executant gpg --list-keys:

$ gpg --list-keys
/Users/schacon/.gnupg/pubring.gpg
---------------------------------
pub   1024D/F721C45A 2009-02-09 [expires: 2010-02-09]
uid                  Scott Chacon <schacon@gmail.com>
sub   2048g/45D02282 2009-02-09 [expires: 2010-02-09]

Llavors, podeu importar directament la clau a la base de dades de Git exportant-la i canalitzant-la a través de git hash-object, que escriu un nou blob amb aquests continguts a Git i us retorna el SHA-1 del blob:

$ gpg -a --export F721C45A | git hash-object -w --stdin
659ef797d181633c87ec71ac3f9ba29fe5775b92

Ara que teniu els continguts de la vostra clau a Git, podeu crear una etiqueta que apunti directament a ella especificant el nou valor SHA-1 que us va donar l’ordre hash-object:

$ git tag -a maintainer-pgp-pub 659ef797d181633c87ec71ac3f9ba29fe5775b92

Si executeu git push --tags, l’etiqueta maintainer-pgp-pub es compartirà amb tots. Si algú vol verificar una etiqueta, poden importar directament la vostra clau PGP traient el blob directament de la base de dades i important-la a GPG:

$ git show maintainer-pgp-pub | gpg --import

Poden utilitzar aquesta clau per verificar totes les vostres etiquetes signades. A més, si incloeu instruccions al missatge de l’etiqueta, executar git show <tag> us permet donar instruccions més específiques a l’usuari final sobre la verificació de l’etiqueta.

Generar un Número de Compilació

Com que Git no té números creixents monotònicament com 'v123' o l’equivalent per anar amb cada commit, si voleu tenir un nom llegible per humans per anar amb un commit, podeu executar git describe en aquest commit. En resposta, Git genera una cadena consistent en el nom de l’última etiqueta anterior a aquest commit, seguit del nombre de commits des d’aquesta etiqueta, seguit finalment d’un valor SHA-1 parcial del commit que es descriu (prefixat amb la lletra "g" que significa Git):

$ git describe master
v1.6.2-rc1-20-g8c5b85c

D’aquesta manera, podeu exportar una instantània o compilació i nomenar-la alguna cosa comprensible per a la gent. De fet, si compileu Git des de codi font clonat del repositori de Git, git --version us dona alguna cosa que sembla això. Si esteu descrivint un commit que heu etiquetat directament, us dona simplement el nom de l’etiqueta.

Per defecte, l’ordre git describe requereix etiquetes anotades (etiquetes creades amb la bandera -a o -s); si voleu aprofitar també les etiquetes lleugeres (no anotades), afegiu l’opció --tags a l’ordre. També podeu utilitzar aquesta cadena com a objectiu d’un ordre git checkout o git show, tot i que depèn del valor SHA-1 abreujat al final, així que pot no ser vàlid per sempre. Per exemple, el nucli de Linux recentment va saltar de 8 a 10 caràcters per assegurar la unicitat de l’objecte SHA-1, així que les sortides anteriors de git describe van ser invalidades.

Preparar una Versió

Ara voleu llançar una compilació. Una de les coses que voldreu fer és crear un arxiu del darrer instantània del vostre codi per a aquelles pobres ànimes que no utilitzen Git. L’ordre per fer això és git archive:

$ git archive master --prefix='project/' | gzip > `git describe master`.tar.gz
$ ls *.tar.gz
v1.6.2-rc1-20-g8c5b85c.tar.gz

Si algú obre aquest tarball, obtindrà l’última instantània del vostre projecte sota un directori project. També podeu crear un arxiu zip de manera molt similar, però passant l’opció --format=zip a git archive:

$ git archive master --prefix='project/' --format=zip > `git describe master`.zip

Ara teniu un bon tarball i un arxiu zip de la versió del vostre projecte que podeu pujar al vostre lloc web o enviar per correu electrònic a la gent.

El Shortlog

És hora d’enviar un correu electrònic a la vostra llista de correu de persones que volen saber què està passant al vostre projecte. Una bona manera d’obtenir ràpidament una mena de registre de canvis del que s’ha afegit al vostre projecte des de l’última versió o correu electrònic és utilitzar l’ordre git shortlog. Resumeix tots els commits al rang que li doneu; per exemple, el següent us dona un resum de tots els commits des de la vostra última versió, si la vostra última versió es deia v1.0.1:

$ git shortlog --no-merges master --not v1.0.1
Chris Wanstrath (6):
      Add support for annotated tags to Grit::Tag
      Add packed-refs annotated tag support.
      Add Grit::Commit#to_patch
      Update version and History.txt
      Remove stray `puts`
      Make ls_tree ignore nils

Tom Preston-Werner (4):
      fix dates in history
      dynamic version method
      Version bump to 1.0.2
      Regenerated gemspec for version 1.0.2

Obteniu un resum net de tots els commits des de v1.0.1, agrupats per autor, que podeu enviar per correu electrònic a la vostra llista.