Source

hgbook / es / mq.tex

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
\chapter{Administración de cambios con Colas de Mercurial}
\label{chap:mq}

\section{El problema de la administración de parches}
\label{sec:mq:patch-mgmt}

Un escenario frecuente: usted necesita instalar un paquete de software
desde las fuentes, pero encuentra un fallo que debe arreglar antes de
poder comenzar a usarlo.  Hace sus cambios, y se olvida del paquete
por un tiempo, unos meses después necesita actualizar a una nueva
versión del paquete.  Si la nueva versión del paquete todavía tiene el
fallo, debe extraer su arreglo del árbol de fuentes anteriores y
aplicarlo a la nueva versión.  Una tarea tediosa en la cual es fácil
equivocarse.

Este es un caso simple del problema del ``manejo de parches''.  Usted
tiene un árbol de fuentes del ``mantenedor principal'' que no puede
cambiar: necesita hacer algunos cambios locales sobre el árbol
principal; y desearía poder mantener tales cambios separados, de forma
tal que pueda aplicarlos a versiones más nuevas del árbol principal.

El problema de administración de parches surge en muchas situaciones.
Probablemente la más visible es cuando un usuario de un proyecto de
software de fuentes abiertas contribuye con un arreglo de un fallo o
una nueva característica a los mantenedores del proyecto en la forma
de un parche.

Aquellos que distribuyen sistemas operativos que incluyen programas
abiertos usualmente requieren hacer cambios en los paquetes que
distribuyen de tal forma que se armen apropiadamente en sus ambientes.

Cuando hay pocos cambios por mantener, es muy sencillo administrar un
solo parche con los programas estándar \command{diff} y
\command{patch} (ver la sección~\ref{sec:mq:patch} para ver cómo
emplear tales herramientas). Cuando la cantidad de cambios comienza a
crecer, tiene sentido mantener parches como ``porciones de trabajo''
individual, de forma que cada cambio contiene solamente un arreglo de
un fallo (el parche puede modificar varios ficheros, pero está
``haciendo una sola cosa''), y puede tener cierta cantidad de tales
parches para diferentes fallos y cambios locales.  En esta situación,
si envía un parche que arregla un fallo a los mantenedores principales
de un paquete y ellos incluyen su arreglo en una publicación
posterior, puede deshacerse de tal parche cuando se actualice a la
nueva versión.

Mantener un solo parche frente a un árbol principal es algo tedioso y
es fácil equivocarse, pero no es difícil.  Aunque, la complejidad del
problema crece rápidamente a medida que la cantidad de parches que
tiene que mantener crece.  Con más que una pequeña cantidad de
cambios, entender cuáles ha aplicado se convierte de algo desordenado
a algo avasallante.

Afortunadamente Mercurial provee una extensión poderos: Colas de
Mercurial (o simplemente ``MQ''), que simplifica en gran medida el
problema de administración de parches.

\section{La prehistoria de las Colas de Mercurial}
\label{sec:mq:history}

A finales de los 90s, muchos desarrolladores del núcleo de Linux
comenzaron a mantener ``series de parches'' que modificaron el
comportamiento del núcleo de Linux.  Algunos se enfocaban en
estabilidad, otros en aumentar las características, y otros un poco
más especulativos.

Los tamaños de las series de parches crecieron rápidamente.  En el
2002, Andrew Morton publicó algunos guiones de línea de órdenes que
estuvo usando para automatizar la tarea de administrar su cola de
parches.  Andrew usó exitósamente tales guiones para administrar
centenas (a veces millares) de parches en el núcleo de Linux.

\subsection{Trabajar parches con quilt}
\label{sec:mq:quilt}

A comienzos del 2003, Andreas Gruenbacher y Martin Quinson tomaron la
aproximación de los guiones de Andrew y publicaron una herramienta
llamada
``patchwork quilt''~\cite{web:quilt}, o simplemente ``quilt''
(ver~\cite{gruenbacher:2005} el paper que lo describe).  Dado que
quilt automatizaba sustancialmente la administración de parches, fue
adoptado en gran medida por desarrolladores de programas abiertos.

Quilt maneja una \emph{pila de parches} sobre un árbol de directorios.
Para comenzar, usted le indica a quilt que administre un árbol de
directorios, le indica qué ficheros manejar; Este almacena los nombres
y los contenidos de estos ficheros.  Para arreglar un fallo, usted
crea un nuevo parche (con una sola orden), edita los ficheros que está
arreglando y ``refresca'' el parche.

El paso de refresco hace que quilt revise el árbol de directorios;
actualiza el parche con todos los cambios que usted haya hecho.  Puede
crear otro parche sobre el primero, que hará seguimiento de los
cambios requeridos para modificar el árbol desde ``el árbol con un
parch aplicado'' a un ``árbol con dos parches aplicados''.

Usted puede \emph{elegir} qué cambios desea aplicar al árbol.  Si
``pop''\ndt{saca} un parche, los cambios hechos por tal parchve
desapareceŕan del árbol de directorios.  Quilt recuerda qué parches ha
sacado, para que pueda ``introducirlos''\ndt{push} posteriormente, así el
árbol de directorios se restaurará con las modificaciones que vienen
del parche.  Lo más importante es que puede ejecutar la orden
``refresh'' en cualquier momento, y el último parche será
actualizado.  Esto significa que puede, en cualquier momento, cambiar
qué parches serán aplicados y qué modificaciones hacen ellos.

Quilt no tiene nada que ver con herramientas de control de versiones,
y puede trabajar bien sobre un conjunto de fuentes que viene de un
fichero comprimido y empaquetado o una copia de trabajo de Subversion.

\subsection{Pasar de trabajo con parches con Quilt hacia Colas de Mercurial}
\label{sec:mq:quilt-mq}

A mediados de 2005, Chris Mason tomó las características de quilt y
escribió una extensión que llamó Colas de Mercurial\ndt{Mercurial
Queues}, que proporcionó un comportamiento a Mercurial al estilo
quilt.

La diferencia clave entre quilt y MQ es que quilt no sabe nada acerca
del sistema de control de revisiones, mientras que MQ está
\emph{integrado} con Mercurial.  Cada parche que usted introduce se
representa como un conjunto de cambios en Mercurial.  Si sustrae un
parche, el conjunto de cambios desaparece.\ndt{introduce originalmente es
push y pop es sustraer en este contexto, usaremos el original en inglés
cuando encontremos que facilita la comprensión}

Dado que quilt no se preocupa por las herramientas de control de
revisiones, continúa siendo una porción de software tremendamente útil
para aquellas situaciones en las cuales no puede usar Mercurial y MQ.

\section{La gran ventaja de MQ}

No puedo sobreestimar el valor que MQ ofrece en la unificación de
parches y el control de revisiones.

La principal razón por la cual los parches han persistido en el mundo
del software libre y de fuentes abiertas--a pesar de la creciente
disponibilidad de herramientas poderosas de control de revisiones-- es
la \emph{agilidad} que ofrecen.

Las herramientas tradicionales de control de revisiones llevan un
registro permanente e irreversible de todo lo que usted hace.  A pesar
de que esto tiene gran valor, también es bastante sutil.  Si requiere
realizar un experimento ((((wild-eyed)))), debe ser cuidadoso en cómo
lo hace, o puede dejar trazas innecesarias--o peor aún,
desconcertantes o desestabilizantes--- de los pasos y errores en el
registro de revisiones de forma permanente.

En contraste, con la cohesión de MQ con el control de revisiones
distribuidos y los parches, resulta más sencillo aislar su trabajo.
Sus parches viven encima del historial de revisiones normales, y
puede hacer que ellos desaparezcan o reaparezcan cuando lo desee.  Si
no le gusta un parche, puede desecharlo.  Si un parche no satisface
todo lo que usted desea, puede arreglarlo---tantas veces como lo
requiera, hasta que lo haya refinado lo suficiente hacia sus
expectativas.

Por ejemplo, la integración de parches con el control de revisiones
hace que el entender los parches y revisar sus efectos---y sus
interacciones con el código en el cuál están enlazados--- sea
\emph{mucho} más sencillo.  Dado que todo parche que se aplique tiene
un conjunto de cambios asociado, puede usar
\hgcmdargs{log}{\emph{filename}} para ver qué conjuntos de cambios y
parches afectaron un fichero.  Puede usar la orden \hgext{bisect} para
hacer una búsqueda binaria sobre todos los conjuntos de cambios y
parches aplicados para ver dónde se introdujo un fallo o dónde fue
arreglado.  Puede usar la orden \hgcmd{annotate} para ver qué
conjuntos de cambios o parches modificaron una línea particular de un
fichero fuente. Y mucho más.

\section{Entender los parches}
\label{sec:mq:patch}

Dado que MQ no esconde su naturaleza parche-céntrica, es muy útil para
entender de qué se tratan los parches, y un poco acerca de las
herramientas que trabajan con ellos.

La orden de Unix tradicional \command{diff} compara dos ficheros, e
imprime una lista de diferencias de sus líneas.  La orden
\command{patch} entiende esas diferencias como \emph{modificaciones}
para construir un fichero.  Vea en la figura~\ref{ex:mq:diff} un
ejemplo sencillo de tales órdenes en acción.

\begin{figure}[ht]
  \interaction{mq.dodiff.diff}
  \caption{Uso sencillo de las órdenes \command{diff} y \command{patch}}
  \label{ex:mq:diff}
\end{figure}

El tipo de fichero que \command{diff} genera (y que \command{patch}
toma como entrada) se llama un ``parche'' o un ``diff''; no hay
diferencia entre un parche y un diff.  (Usaremos el término ``parche'',
dado que es el que más comunmente se usa.)

Un parche puede comenzar con un texto arbitrario; la orden \command{patch}
ignora este texto, pero MQ lo usa como el mensaje de consignación
cuando se crean conjuntos de cambios.  Para encontrar el inicio del
contenido de un parche, la orden \command{patch} busca la primera
línea que comience con la cadena ``\texttt{diff~-}''.

MQ trabaja con diffs \emph{unificados} (\command{patch} acepta varios
formatos de diff adicionales, pero MQ no).  Un diff unificado contiene
dos clases de encabezados.  El \emph{encabezado de fichero} describe
el fichero que se está modificando; contiene el nombre del fichero a
modificar.  Cuando \command{patch} ve un nuevo encabezado de fichero,
busca un fichero con ese nombre para modificarlo.

Después del encabezaado vienen varios \emph{trozos}.  Cada trozo
comienza con un encabezado; que identifica el rango de líneas del
fichero que el trozo debe modificar.  Después del encabezado, un trozo
comienza y termina con unas pocas líneas (usualmente tres) de texto del
fichero que no han sido modificadas; las cuales llamamos el
\emph{contexto} del trozo.  Si solamente hay una pequeña cantidad de
contexto entre trozos sucesivos, \command{diff} no imprime un nuevo
encabezado para el trozo, continua integrando los trozos, con unas
líneas de contexto entre las modificaciones.

Cada línea de contexto comienza con un caracter de espacio.  En el
trozo, si una línea comienza con ``\texttt{-}'' significa ``elimine
esta línea'', si la línea comienza con un ``\texttt{+}'' significa
``inserte esta línea''.  Por ejemplo, una línea que se modifica se
representa con una línea eliminada y una línea insertada.

Retomaremos aspectos más sutiles acerca de parches posteriormente (en
la sección~\ref{sec:mq:adv-patch}), pero en el momento usted ya
debería tener suficiente información para usar MQ.

\section{Comenzar a usar Colas de Mercurial}
\label{sec:mq:start}

Dado que MQ está implementado como una extensión, debe habilitarla
explícitamente antes de comenzar a usarla.  (No necesita descargar
nada; MQ viene con la distribución estándar de Mercurial.)  Para
habilitar MQ, edite su fichero \tildefile{.hgrc}, y añada las líneas
de la figura~\ref{ex:mq:config}.

\begin{figure}[ht]
  \begin{codesample4}
    [extensions]
    hgext.mq =
  \end{codesample4}
  \label{ex:mq:config}
  \caption{Líneas a añadir en \tildefile{.hgrc} para habilitar la extensión MQ}
\end{figure}

Cuando la extensión esté habilitada, aparecerán varios comandos.  Para
verificar que la extensión está trabajando, puede usar \hgcmd{help}
para ver si la orden \hgxcmd{mq}{qinit} está disponible; vea un
ejemplo en la figura~\ref{ex:mq:enabled}.

\begin{figure}[ht]
  \interaction{mq.qinit-help.help}
  \caption{Cómo verificar que MQ está habilitado}
  \label{ex:mq:enabled}
\end{figure}

Puede usar MQ en \emph{cualquier} repositorio de Mercurial, y sus
comandos solamente operarán con tal repositorio.  Para comenzar, basta
con preparar el repositorio con la orden \hgxcmd{mq}{qinit} (ver la
figura~\ref{ex:mq:qinit}).  Esta orden crea un directorio vacío
llamado \sdirname{.hg/patches}, donde MQ mantendrá sus metadatos. Como
otras ordenes de Mercurial, la orden \hgxcmd{mq}{qinit} no imprime
nada cuando es exitosa.

\begin{figure}[ht]
  \interaction{mq.tutorial.qinit}
  \caption{Preparar un repositorio para usar MQ}
  \label{ex:mq:qinit}
\end{figure}

\begin{figure}[ht]
  \interaction{mq.tutorial.qnew}
  \caption{Crear un nuevo parche}
  \label{ex:mq:qnew}
\end{figure}

\subsection{Crear un nuevo parche}

Para comenzar a trabajar en un nuevo parche use la orden
\hgxcmd{mq}{qnew}. Esta orden recibe un argumento, el nombre del
parche a crear.  MQ lo usará como el nombre del fichero en el
directorio \sdirname{.hg/patches}, como puede apreciarlo en la
figura~\ref{ex:mq:qnew}.

También hay otros dos nuevos ficheros en el directorio
\sdirname{.hg/patches}:  \sfilename{series} y \sfilename{status}.  El
fichero \sfilename{series} lista todos los parches de los cuales MQ
tiene noticia para este repositorio, con un parche por línea.
Mercurial usa el fichero \sfilename{status} para mantener registros
interns; da seguimiento a todos los parches que MQ ha \emph{aplicado}
en el repositorio.

\begin{note}
  En ciertas ocasiones usted querrá editar el fichero
  \sfilename{series} a mano; por ejemplo, cambiar el orden en que se
  aplican ciertos parches.  A pesar de esto, es una mala idea editar
  manualmente  el fichero \sfilename{status}, dado que es fácil
  desorientar a MQ acerca de lo que está pasando.
\end{note}

Una vez que haya creado un nuevo parche, puede editar los ficheros en
el directorio de trabajo, como lo haría usualmente.  Toda las órdenes
que de a Mercurial, tales como \hgcmd{diff} y \hgcmd{annotate},
trabajarán de la misma forma como lo han hecho antes.

\subsection{Refrescar un parche}

Cuando usted llega a un punto en el cual desea guardar su trabajo, use
la orden \hgxcmd{mq}{qrefresh} (figura~\ref{ex:mq:qnew}) para
actualizar el parche en el cual está trabajando.  Esta orden almacena
los cambios que haya hecho al directorio actual de trabajo en su
parche, y almacena el conjunto de cambios correspondiente que contiene
los cambios.

\begin{figure}[ht]
  \interaction{mq.tutorial.qrefresh}
  \caption{Refrescar un parche}
  \label{ex:mq:qrefresh}
\end{figure}

Puede ejecutar la orden \hgxcmd{mq}{qrefresh} tan seguido como quiera,
y es una buena forma de ``colocar marcas'' a su trabajo.  Refresque su
parche en momentos oportunos; intente un experimento; si el
experimento no funciona, Use \hgcmd{revert} sobre sus modificaciones
para volver al refresco anterior.

\begin{figure}[ht]
  \interaction{mq.tutorial.qrefresh2}
  \caption{Refrescar un parche muchas veces para acumular cambios}
  \label{ex:mq:qrefresh2}
\end{figure}

\subsection{Aplicar un parche tras otro y dar seguimiento}

Cuando haya terminado de trabajar en un parche, o necesite trabajar en
otro, puede usar la orden \hgxcmd{mq}{qnew} para crear un nuevo
parche.  Mercurial aplicará este parche sobre su parche anterior.
Para un ejemplo, ver la figura~\ref{ex:mq:qnew2}.  Note que el parche
contiene los cambios en nuestro parche anterior como parte de su
contexto (lo verá más claramente en la salida de \hgcmd{annotate}).

\begin{figure}[ht]
  \interaction{mq.tutorial.qnew2}
  \caption{Aplicar un parche después del primero}
  \label{ex:mq:qnew2}
\end{figure}

Hasta ahora, con excepción de \hgxcmd{mq}{qnew} y
\hgxcmd{mq}{qrefresh}, hemos sido cuidadosos para aplicar únicamente
órdenes usuaales de Mercurial.  De todas maneras, MQ ofrece muchos
comandos que son más sencillos de usar cuando esté pensando acerca de
parches, como se puede ver en la figura~\ref{ex:mq:qseries}:

\begin{itemize}
\item La orden \hgxcmd{mq}{qseries} lista cada parche del cual MQ
  tiene noticia en este repositorio, desde el más antiguo hasta el más
  nuevo (El último \emph{creado}).
\item La orden \hgxcmd{mq}{qapplied} lista cada parche que MQ haya
  \emph{aplicado} en este repositorio, de nuevo, desde el más antiguo
  hasta el más nuevo (El aplicado más recientemente).
\end{itemize}

\begin{figure}[ht]
  \interaction{mq.tutorial.qseries}
  \caption{Entender la pila de parches con \hgxcmd{mq}{qseries} y
    \hgxcmd{mq}{qapplied}}
  \label{ex:mq:qseries}
\end{figure}

\subsection{Manipular la pila de parches}

La discusión previa indicó que debe haber una diferencia entre los
parches ``conocidos'' y ``aplicados'', y efectivamente la hay.  MQ
puede manejar un parche sin que este haya sido aplicado al
repositorio.

Un parche \emph{aplicado} tiene su correspondiente conjunto de cambios
en el repositorio, y los efectos del parche y el conjunto de cambios
son visibles en el directorio de trabajo.  Puede deshacer la
aplicación de un parche con la orden \hgxcmd{mq}{qpop}.  MQ 
\emph{sabe acerca de}, o maneja un parche sustraído, pero el parche ya
no tendrá un conjunto de cambios correspondientes en el repositorio, y
el directorio de trabajo no contendrá los cambios hechos por el
parche.  La figura~\ref{fig:mq:stack} ilustra la diferencia entre
parches aplicados y seguidos.

\begin{figure}[ht]
  \centering
  \grafix{mq-stack}
  \caption{Parches aplicados y no aplicados en la pila de parches de MQ}
  \label{fig:mq:stack}
\end{figure}

Puede reaplicar un parche no aplicado o sustraído con la orden
\hgxcmd{mq}{qpush}.  Esto crea un nuevo conjunto de cambios
correspondiente al parche, y los cambios del parche estarán presentes
de nuevo en el directorio de trabajo.  Vea ejemplos de
\hgxcmd{mq}{qpop} y \hgxcmd{mq}{qpush} en acción en la
figura~\ref{ex:mq:qpop}.  Vea que hemos sustraído uno o dos parches,
la salida de\hgxcmd{mq}{qseries} continúa igual, mientras que
\hgxcmd{mq}{qapplied} ha  cambiado.

\begin{figure}[ht]
  \interaction{mq.tutorial.qpop}
  \caption{Modificar la pila de parches aplicados}
  \label{ex:mq:qpop}
\end{figure}

\subsection{Introducir y sustraer muchos parches}

Mientras que \hgxcmd{mq}{qpush} y \hgxcmd{mq}{qpop} operan sobre un
único parche cada vez, puede introducir y sustraer varios parches de
una vez.  La opción \hgxopt{mq}{qpush}{-a} de \hgxcmd{mq}{qpush}
introduce todos los cambios que no hayan sido aplicados, mientras que
la opción \hgxopt{mq}{qpop}{-a} de \hgxcmd{mq}{qpop} sustrae todos los
cambios aplicados.  (Vea la sección~\ref{sec:mq:perf} más adelante
en la cual se explican otras formas de de introducir y sustraer varios
cambios.)

\begin{figure}[ht]
  \interaction{mq.tutorial.qpush-a}
  \caption{Pushing all unapplied patches}
  \label{ex:mq:qpush-a}
\end{figure}

\subsection{Medidas de seguridad y cómo saltarlas}

Muchas órdenes MQ revisan el directorio de trabajo antes de hacer
cualquier cosa, y fallan si encuentran alguna modificación.  Lo hacen
para garantizar que usted no pierda cambio alguno de los que haya
hecho, pero que no hayan sido incorporados en algún parche.  La
figura~\ref{ex:mq:add} ilusta esto; la orden \hgxcmd{mq}{qnew} no
creará un nuevo parche si hay cambios notorios, causados en este caso
por aplicado la orden \hgcmd{add} a \filename{file3}.

\begin{figure}[ht]
  \interaction{mq.tutorial.add}
  \caption{Crear un parche a la fuerza}
  \label{ex:mq:add}
\end{figure}

Las órdenes que revisan el directorio actual cuentan con una opción
``Se lo que estoy haciendo'', que siempre está nombrada como
\option{-f}.  El significado exacto de \option{-f} depende de la
orden.  Por ejemplo, \hgcmdargs{qnew}{\hgxopt{mq}{qnew}{-f}}
incorporarán cualquier cambio notorio en el nuevo parche que crea pero
\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-f}} revertirá las modificaciones a
cualquier fichero que haya sido afectado por el parche que está siendo
sustraído. ¡Asegúrese de leer la documentación de la opción \option{-f}
de cada comando antes de usarla!

\subsection{Trabajar con varios parches a la vez}

La orden \hgxcmd{mq}{qrefresh} siempre refresca el \emph{último}
parche aplicado.  Esto significa que usted puede suspender su trabajo
en un parche (refrescándolo), sustraerlo o introducirlo para lograr
que otro parche esté de último y trabajar en \emph{ese} parche por un
rato.

A continuación un ejemplo que ilustra cómo puede usar esta habilidad.
Digamos que está desarrollando una nueva característica en dos
parches.  El primero es un cambio en la parte fundamental de su
programa, y el segundo--sobre el primero---cambia la interfaz de
usuario para usar el código que ha añadido a la parte fundamental.  Si
ve que hay un fallo en la parte fundamental mientras está trabajando
en el parche de UI\ndt{Interfaz de Usuario, User Interface en inglés}, es fácil arreglar la parte fundamental.
Simplemente use \hgxcmd{mq}{qrefresh} sobre el parche de la UI para
guardar los cambios de su trabajo en progreso, y use \hgxcmd{mq}{qpop}
para sacar sustraer el parche de la parte fundamental.  Arregla el
fallo sobre la parte fundamental, aplique \hgxcmd{mq}{qrefresh} sobre
el parche fundamental, y aplique \hgxcmd{mq}{qpush} sobre el parche de
UI para continuar donde había quedado.

\section{Más acerca de parches}
\label{sec:mq:adv-patch}

MQ usa la orden GNU \command{patch} para aplicar los parches, por lo
tanto es útil conocer ciertos detalles de cómo trabaja
\command{patch}, y también acerca de los parches.

\subsection{La cantidad de franjas}

Si ve el encabezado de un parche, notará que la ruta al fichero tiene
un componente adicional al principio, que no está presente en la
ruta. Esta es una traza de cómo generaba anteriormente los parches la
gente (algunos aún lo hacen, pero es raro con las herramientas de
control de revisiones del actuales).

Alicia desempaquetaría un comprimido, editaría sus ficheros, y querría
crear un parche.  Por lo tanto ella renombraría su directorio de
trabajo, desempacaría el comprimido de nuevo (para lo cual necesitó el
renombramiento), y usaría las opciones \cmdopt{diff}{-r} y
\cmdopt{diff}{-N} de \command{diff} para generar recursivamente un
parche entre el directorio original y el modificado.  El resultado
sería que el nombre del directorio original estaría al principio de
toda ruta en cada encabezado de fichero, y el nombre del directorio
modificado estaría al frente de la porción derecha de la ruta del
fichero.

Como alguien que reciba un parche de Alicia en la red podría obtener
dos directorios, uno original y el otro modificado con exactamente los
mismos nombres, la orden \command{patch} tiene la opción
\cmdopt{patch}{-p} que indica la cantidad de componentes de la ruta
a eliminar cuando se vaya a aplicar el parche.  Este número se
llama la \emph{cantidad de eliminaciones}.

La opción con ``\texttt{-p1}'' significa ``elimine uno''.  Si
\command{patch} ve un nombre de fichero \filename{foo/bar/baz} en el
encabezado del fichero, eliminará \filename{foo} y tratará de parchar
un fichero llamado \filename{bar/baz}.  (Hablando estrictamente, la
cantidad de eliminaciones se refiere a la cantidad de \emph{separadores de
 ruta} (y los componentes que vayan con ellos) a eliminar.  Si el
contador es uno volverá \filename{foo/bar} en \filename{bar}, pero
\filename{/foo/bar} (note la barra extra) en \filename{foo/bar}.)

La cantidad a eliminar``estándar'' para parches es uno; casi todos los
parches contienen un componente inicial de la ruta que necesita ser
eliminado.  La orden \hgcmd{diff} de Mercurial genera nombres de ruta
de esta forma, y la orden \hgcmd{import} y MQ esperan parches que
tengan a uno como cuenta de eliminaciones.

Si recibe un parche de alguien de quien desea adicionar adicionar a su
cola de parches, y el parche necesita una cuenta de eliminación que no
sea uno, no podrá aplicar \hgxcmd{mq}{qimport} en primera medida,
porque \hgxcmd{mq}{qimport} no tiene todavía una opción \texttt{-p}
option (ver~\bug{311}).  Lo mejor que puede hacer es aplicar
\hgxcmd{mq}{qnew} por su cuenta, y después usar \cmdargs{patch}{-p\emph{N}}
para aplicar tal parche, seguido de \hgcmd{addremove} para tener en
cuenta cualquier fichero adicionado o eliminado por el parche, seguido
de \hgxcmd{mq}{qrefresh}.  Esta complejidad puede ser innecesaria;
consulte~\bug{311} para más información.

\subsection{Estrategias para aplicar parches}

Cuando \command{patch} aplica un trozo, intenta varias estrategias
sucesivas que decrecen en precisión para intentar aplicarlo.  Esta
técnica de pruebas y error aveces permite que un parche que fue
generado contra una versión anterior de un fichero, sea aplicada sobre
una versión más nueva del mismo.

Primero \command{patch} intenta una correspondencia perfecta donde los
números de línea, el contexto y el texto a modificar deben coincidir
perfectamente.  Si no lo logra, intenta encontrar una correspondencia
exacta del contexto, sin tener en cuenta el número de línea.  Si es
exitoso, imprime una línea indicando que el trozo fue aplicado, pero a
un \emph{corrimiento} del número de línea original.

Si falla la correspondencia por contexto, \command{patch} elimina la
primera y la última línea del contexto, e intenta una correspondencia
\emph{reducida} del contexto.  Si el trozo con contexto reducido es
exitoso, imprime un mensaje indicando que aplicó el trozo con un
\emph{factor difuso} (el número después del factor difuso indica
cuántas líneas de contexto \command{patch} tuvo que eliminar antes de
aplicar el parche).

Cuando ninguna de estas técnicas funciona, \command{patch} imprime un
mensaje indicando que el trozo en cuestión se desechó.  Almacena los
trozos desechados (también llamados ``descartados'') en un fichero con
el mismo nombre, y la extensión \sfilename{.rej} añadida.  También
almacena una copia igual al fichero original con la extensión
\sfilename{.orig}; la copia del fichero sin extensión contendrá
cualquier cambio hecho por los trozos que \emph{} se aplicaron sin
problema.  Si usted tiene un parche que modifica \filename{foo} con
seis trozos, y uno de ellos falla al aplicarse, tendrá : un fichero
original \filename{foo.orig}, un fichero \filename{foo.rej} que
contiene el trozo, y \filename{foo}, que contiene los cambios que se
aplicaron por los cinco trozos exitosos.

\subsection{Algunos detalles de la representación de parches}

Hay ciertas cosas útiles por saber acerca de cómo trabaja
\command{patch} con los ficheros:
\begin{itemize}
\item Debería ser obvio que \command{patch} no puede manipular
  ficheros binarios.
\item No se preocupa por el bit ejecutable; crea ficheros nuevos en
  modo lectura, pero no ejecutable.
\item \command{patch} intenta eliminar un fichero como una diferencia
  entre el fichero a eliminar y un fichero vacío.  Y por lo tanto su
  idea de ``Borré este fichero'' debería pensarse como ``toda línea de
  este fichero fue eliminada'' en un parche.
\item Trata la adición de un fichero como un diff entre un fichero
  vacío y el fichero a ser adicionado.  Por lo tanto en un parche su
  idea de ``Añadí este fichero'' se vería como ``toda línea de este
  fichero fue añadida''.
\item Trata el renombramiento de un fichero como la eliminación del
  nombre anterior y la adición del nuevo nombre.  Esto significa que
  los ficheros renombrados dejan un rastro grande en los parches.
  (Tenga en cuenta que Mercurial no trata de inferir cuando los
  ficheros han sido renombrados o copiados en un parche en este
  momento.)
\item \command{patch} no puede representar ficheros vacíos, por lo
  tanto no puede usar un parche para representar la noción ``Añadí
  este fichero vacío al árbol''.
\end{itemize}
\subsection{Cuidado con los difusos}

Cuando aplique un trozo con un corrimiento, o con un factor difuso,
aveces será taotalmente exitoso, tales técnicas inexactas dejan
claramente la posibilidad de corromper el fichero parchado.  Los casos
más típicos involucran aplicar un parche dos veces o en un sitio
incorrecto del fichero. Si \command{patch} o \hgxcmd{mq}{qpush} llegan
a mencionar un corrimiento o un factor difuso, debería asegurarse que
los ficheros modificados estén correctos después del suceso.

Casi siempre es buena idea refrescar un parche que fue aplicado con un
corrimiento o un factor difuso; refrescar el parche genera nueva
información de contexto que permitirá aplicarlo limpiamente.  Digo
``casi siempre,'' no ``siempre'', puesto que en ciertas ocasiones
refrescar un parche lo hará fallar frente a una revisión diferente del
fichero.  En algunos casos, como por ejemplo, cuando usted está
manteniendo un parche que debe estar encima de múltiples revisiones de
un árbol de fuentes, es aceptable tener un parche aplicado algo
difuso, siempre que haya verificado los resultados del proceso de
parchar.

\subsection{Manejo de descartes}

Si \hgxcmd{mq}{qpush} falla al aplicar un parche, mostrará un texto de
error y saldrá.  Si ha dejado ficheros \sfilename{.rej}, es mejor
arreglar los trozos descartados antes de introducir parches
adicionales o hacer cualquier otra cosa.

Si su parche \emph{solía} aplicarse limpiamente, y ya no lo hace
porque ha cambiado código subyacente en el cual se basa su parche, las
Colas de Mercurial pueden ayudar; consulte la sección~\ref{sec:mq:merge}.

Desafortunadamente, no hay grandes técnicas para tratar los trozos
descartados.  Casi siempre deberá consultar el fichero
\sfilename{.rej} y editar el fichero objetivo, aplicando los trozos
descartados a mano.

Si es aventurero, Neil Brown, un hacker del núcleo Linux, escribió una
herramienta llamada \command{wiggle}~\cite{web:wiggle}, que es más
vigorosa que \command{patch} en su intento de hacer que se aplique un
parche.

Otro hacker del nucleo Linux, Chris Mason (el autor de las Colas de
Mercurial), escribió una herramienta similar llamada
\command{mpatch}~\cite{web:mpatch}, que sigue una aproximación
sencilla para automatizar la aplicación de trozos descartados por
\command{patch}.  La orden \command{mpatch} puede ayudar con cuatro
razones comunes por las cuales un parche ha sido descartado:

\begin{itemize}
\item El contexto en la mitad de un trozo ha cambiado.
\item Un trozo ha perdido cierto contexto al principio o al final.
\item Un trozo largo podría aplicarse mejor---por completo o una
  parte---si estaba cortado en trozos más pequeños.
\item Un trozo remueve líneas con contenido ligeramente diferente que
  aquellas que están presentes en el fichero.
\end{itemize}

Si usted usa \command{wiggle} o \command{mpatch}, debería ser
doblemente cuidadoso al revisar sus resultados cuando haya terminado.
De hecho, \command{mpatch} refuerza este método de revisar por partida
doble su salida, dejándolo a usted en un programa de fusión cuando la
herramienta haya terminado su trabajo, de tal forma que usted pueda
verificar lo que ha hecho y pueda terminar de aplicar cualquier fusión
faltante.

\section{maximizar el rendimiento de MQ}
\label{sec:mq:perf}

MQ es muy eficiente al tratar con una gran cantidad de parches.  Corrí
unos experimentos de desempeño a mediados del 2006 para una charla que
dí en la conferencia EuroPython 2006~\cite{web:europython}.  Empleé la
serie de parches para el núcleo Linux 2.6.17-mm1, que contaba con 1.738
parches.  Los apliqué sobre un repositorio del núcleo de Linux con
todas las 27.472 revisiones entre 2.6.12-rc2 y 2.6.17.

En mi portátil antiguo y lento, logré aplicar 
\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} a los 1.738 parches en 3.5
minutos, y \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} en 30 segundos.
(En un portátil más nuevo, el tiempo para introducir todos los
parches, se logró en menos de dos minutos.)  Apliqué
\hgxcmd{mq}{qrefresh} sobre uno de los parches más grandes (que hizo
22.779 líneas de cambios en 287 ficheros) en 6,6 segundos.

Claramente, MQ funciona adecuadamente en árboles grandes, y además hay
unos trucos que pueden emplearse para obtener el máximo desempeño.

En primer lugar, trate de hacer ``en lote'' las operaciones.  Cada vez
que ejecute \hgxcmd{mq}{qpush} o \hgxcmd{mq}{qpop}, tales órdenes
revisan el directorio de trabajo para asegurarse de que usted no ha
hecho cambios y ha olvidado ejecutar \hgxcmd{mq}{qrefresh}.  En un
árbol pequeño, el tiempo de esta revisión puede ser mínimo,  Pero en
un árbol mediano (con decenas de miles de ficheros), puede tomar un
segundo o más.

Las órdenes \hgxcmd{mq}{qpush} y \hgxcmd{mq}{qpop} le permiten
introducir o sustraer varios parches en una operación.  Puede
identificar el ``parche destino'' que desee.  Cuando aplique
\hgxcmd{mq}{qpush} con un destino, introducirá tantos parches como sea
necesario hasta que el especificado esté en el tope de la pila.
Cuando emplee \hgxcmd{mq}{qpop} con un destino, MQ sustraerá parches
hasta que el parche destino esté en el tope.

Puede identificar un parche destino con el nombre del parche o con el
número.  Si se refiere al número, los parches se contarán desde cero;
esto significa que el primer parche es cero, el segundo es uno y así
sucesivamente.

\section{Actualiar los parches cuando el código cambia}
\label{sec:mq:merge}

Es común contar con una pila de parches sobre un repositorio que usted
no modifica directamente.  Si está trabajando en cambios de código de
otros, o en una característica que tarda bastante en desarrollarse
comparada con la tasa de cambio del código sobre la cual se está
trabajando, necesitará sincronizarse con el código, y ajustar
cualquier trozo en sus parches que ya no estén al día.  A esto se le
llama hacer \emph{rebase} a su serie de parches.

La vía más sencilla de hacerlo es con \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}}
sobre sus parches, después hacer \hgcmd{pull} de los cambios en el
repositorio, y finalmente hacer
\hgcmdargs{qpush}{\hgxopt{mq}{qpop}{-a}} con sus parches de nuevo.  MQ
dejará de de introducir parches siempre que llegue a un parche que no se pueda
aplicar debido a un conflicto, permitiéndole a usted arreglarlo,
aplicar \hgxcmd{mq}{qrefresh} al parche afectado y continuar
introduciendo hasta que haya arreglado la pila completa.

Esta aproximación es sencilla y funciona bien si no espera cambios en
el código original que afecte en gran medida los parches que usted
esté aplicando. Si su pila de parches toca código que es modificado
frecuentemente o de forma invasiva sobre el código subyacente,
arreglar trozos manualmente se vuelve desgastante.

Es posible automatizar de forma parcial el proceso de rebase.  Si sus
parches se aplican limpiamente sobre algunas revisiones del
repositorio subyacente, MQ puede usar esta información para ayudarle a
a resolver conflictos entre sus parches y una revisión distinta.

El proceso resulta un poco complejo:
\begin{enumerate}
\item Para comenzar, haga \hgcmdargs{qpush}{-a} sobre todos los
  parches que usted sepa se aplican limpiamente.
\item Guarde una copia de seguridad de su directorio de parches  con
  \hgcmdargs{qsave}{\hgxopt{mq}{qsave}{-e} \hgxopt{mq}{qsave}{-c}}.
  Esto imprime el nombre del directorio en el cual se han guardado los
  parches.  Guardará los parches en un directorio llamado
  \sdirname{.hg/patches.\emph{N}}, donde \texttt{\emph{N}} es un
  entero pequeño.  También consigna un ``conjunto de cambios de
  seguridad'' sobre sus parches aplicados; esto es para mantener el
  histórico, y guarda los estados de los ficheros  \sfilename{series}
  y \sfilename{status}.
\item Use \hgcmd{pull} para traer los nuevos cambios en el repositorio
  subyacente. (No ejecute \hgcmdargs{pull}{-u}; vea más adelante por qué.)
\item Actualice a la nueva revisión punta con 
  \hgcmdargs{update}{\hgopt{update}{-C}} para sobreescribir los
  parches que haya introducido.
\item Fusione todos los parches con \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}
    \hgxopt{mq}{qpush}{-a}}.  La opción \hgxopt{mq}{qpush}{-m} de \hgxcmd{mq}{qpush}
  le indica a MQ que haga una fusión que involucra tres fuentes si el
  parche falla al aplicarse.
\end{enumerate}

Durante el \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}}, cada parche en
el fichero \sfilename{series} se aplica normalmente.  Si un parche se
aplica difusamente o se niea a aplicarse, MQ consulta la cola que
usted guardó con \hgxcmd{mq}{qsave}, y aplica una fusión de tres con
el correspondiente conjunto de cambios.  Esta fusión usa la maquinaria
de Mercurial, por lo tanto puede mostrar una herramienta de fusión GUI
para ayudarle a resolver los problemas.

Cuando termine de resolver los efectos de un parche, MQ refrescará su
parche basado en el resultado de la fusión.

Al final de este proceso, su repositorio tendrá una cabeza extra de la
antigua cola de parches, y una copia de la cola de parches anterio
estará en \sdirname{.hg/patches.\emph{N}}. Puede eliminar la cabeza
extra con \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a} \hgxopt{mq}{qpop}{-n} patches.\emph{N}}
o \hgcmd{strip}.  Puede eliminar \sdirname{.hg/patches.\emph{N}} una
vez que esté seguro de que no lo necesita más como copia de seguridad.

\section{Identificar parches}

Las órdenes de MQ le permiten trabajar refiriéndose al nombre del
parche o al número.  Es obvio hacerlo por el nombre; por ejemplo se
pasa el nombre \filename{foo.patch} a \hgxcmd{mq}{qpush}, que
introducirá los parches hasta que \filename{foo.patch} se aplique.  

Para hacerlo más corto, puede referirse a un parche con un nombre y un
corrimiento de número; por ejemplo,  \texttt{foo.patch-2} significa
``dos parches antes de \texttt{foo.patch}'', mientras que
\texttt{bar.patch+4} significa ``cuatro parches después de \texttt{bar.patch}''.

Referirse a un parche por su índice no es muy diferente.  El primer
parche que se imprime en la salida de \hgxcmd{mq}{qseries} es el
parche cero (si, es el primero en los sistemas que comienzan su conteo
en cero); el segundo parche es uno y así sucesivamente.

MQ facilita el trabajo cuando está usando órdenes normales de
Mercurial.  Cada comando que acepte Identificadores de conjuntos de
cambios también aceptará el nombre de un parche aplicado.  MQ aumenta
las etiquetas normalmente en el repositorio con un distintivo para cada
parche aplicado.  Adicionalmente, las etiquetas especiales \index{tags!special tag
  names!\texttt{qbase}}\texttt{qbase} y \index{tags!special tag
  names!\texttt{qtip}}\texttt{qtip} identifican los parches
``primero'' y último, respectivamente.

Junto con las capacidades de Mercurial para etiquetar, estas adiciones
hacen que trabajar con parches sea muy sencillo.
\begin{itemize}
\item ¿Desea enviar una bomba de parches a una lista de correo con los
  últimos cambios que ha hecho?
  \begin{codesample4}
    hg email qbase:qtip
  \end{codesample4}
  (¿No sabe qué es una ``bomba de parches''?  Consulte la
  sección~\ref{sec:hgext:patchbomb}.)
\item ¿Desea ver todos los parches desde que se aplicó
  \texttt{foo.patch} sobre los ficheros de un subdirectorio en su
  árbol?
  \begin{codesample4}
    hg log -r foo.patch:qtip \emph{subdir}
  \end{codesample4}
\end{itemize}

Dado que MQ nombra los parches disponibles al resto de Mercurial con
su maquinaria de etiquetas interna, usted no necesita teclear el
nombre completo de un parche cuando desea identificarlo por su nombre.

\begin{figure}[ht]
  \interaction{mq.id.output}
  \caption{Uso de las características de etiquetamiento al trabajar
    con MQ}
  \label{ex:mq:id}
\end{figure}

Otra consecuencia deseable al representar los nombres de parches como
etiquetas es que cuando ejecute la orden \hgcmd{log}, desplegará el
nombre del parche como una etiqueta, usualmente con la salida normal.
Esto facilita distinguir visualmente los parches aplicados de las
revisiones ``normales''.  La figura~\ref{ex:mq:id} muestra algunos
comandos usuales de Mercurial al trabajar con parches.

\section{Otra información útil}

Hay una cantidad de aspectos que hacen que el uso de MQ no representen
secciones en sí mismas, pero de los cuales es bueno estar
enterado. Los presentamos en aquí:

\begin{itemize}
\item Usualmente cuando hace \hgxcmd{mq}{qpop} a un parche y vuelve a
  hacerle \hgxcmd{mq}{qpush}, el conjunto de cambios que representa el
  parche después de introducir/sustraer tendrá una  \emph{identidad
    distinta} que aquella que representaba el conjunto de cambios
  anteriormente. Consulte la  secctión~\ref{sec:mqref:cmd:qpush} para
  obtener información del por qué de esto.
\item No es una buena idea aplicar \hgcmd{merge} de cambios de otra
  rama con un conjunto de cambios de parches, por lo menos si desea
  mantener la ``información de parches'' de ese conjunto de cambios y
  los conjuntos de cambios que se encuentran por debajo en la pila de
  parches.  Si intenta hacerlo, parecerá que ha sido exitoso, pero MQ
  se confundirá.
\end{itemize}

\section{Administrar parches en un repositorio}
\label{sec:mq:repo}

Dado que el directorio \sdirname{.hg/patches} de MQ reside fuera del
repositorio de trabajo de Mercurial, el repositorio ``subyacente'' de
Mercurial no sabe nada acerca de la administración o presencia de
parches.

Esto presenta la interesante posibilidad de administrar los contenidos
del directorio de parches como un repositorio de Mercurial por su
cuenta.  Puede ser una forma útil de trabajar.  Por ejemplo, puede
trabajar en un parche por un rato, hacerle \hgxcmd{mq}{qrefresh} y
después hacer \hgcmd{commit} al estado actual del parche.  Esto le
permite ``devolverse'' a esa versión del parche posteriormente.

Puede también compartir diferentes versiones de la misma pila de
parches entre varios repositorios subyacentes.  Uso esto cuando estoy
desarrollando una característica del núcleo Linux.  Tengo una copia
original de las fuentes del núcleo para varias arquitecturas, y cloné
un rpositorio en cada una que contiene los parches en los cuales
estoy trabajando.  Cuando quiero probar un cambio en una arquitectura
diferente, introduzco mis parches actuales al repositorio de parches
asociado con el árbol del kernel, sustraigo e introduzco todos mis
parches, armo y pruebo el núcleo.

Llevar los parches en un repositorio permite que varios
desarrolladores puedan trabajar en la misma serie de parches sin
sobreponerse, todo sobre la fuente base subyacente que pueden o no
controlar.

\subsection{Soporte de MQ para repositorios de parches}

MQ le ayuda a trabajar con el directorio \sdirname{.hg/patches} como
un repositorio; cuando usted prepara un repositorio para trabajar con
parches usando \hgxcmd{mq}{qinit}, puede pasarle la opción
\hgxopt{mq}{qinit}{-c} para que se cree el directorio
\sdirname{.hg/patches} como un repositorio de Mercurial.

\begin{note}
  Si olvida usar la opción \hgxopt{mq}{qinit}{-c} option, puede ir al
  directorio \sdirname{.hg/patches} en cualquier momento y ejecutar
  \hgcmd{init}.  No olvide añadir una entrada en el fichero
  \sfilename{status} del fichero \sfilename{.hgignore}, a pesar de que
  (\hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} hace estodo de forma
  automática para usted); usted \emph{seguro} no quiere administrar el
  fichero \sfilename{status}.
\end{note}

MQ nota convenientemente que el directorio \dirname{.hg/patches}
es un repositorio, hará \hgcmd{add} automáticamente a cada parche que
usted cree e importe.

MQ provee una orden corta, \hgxcmd{mq}{qcommit}, que ejecuta
\hgcmd{commit} en el directorio \sdirname{.hg/patches}.  Lo que ahorra
tecleo recurrente.

Finalmente, para administrar convenientemente el directorio de
parches, puede definir el alias \command{mq} en sistemas Unix.  Por
ejemplo, en sistemas Linux con el intérprete \command{bash}, puede
incluir el siguiente recorte de código\ndt{snippet} en su fichero
\tildefile{.bashrc}.

\begin{codesample2}
  alias mq=`hg -R \$(hg root)/.hg/patches'
\end{codesample2}

Puede aplicar las órdenes de la forma \cmdargs{mq}{pull} al
repositorio principal.

\subsection{Detalles a tener en cuenta}

El soporte de MQ para trabajar con un repositorio de parches es
limitado en ciertos aspectos:

MQ no puede detectar automáticamente los cambios que haga al
directorio de parches.  Si aplica \hgcmd{pull}, edita manualmente, o
hace \hgcmd{update} a los parches o el fichero \sfilename{series},
tendrá que aplicar \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} y después
\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} en el repositorio subyacente
para que los cambios se reflejen allí.  Si olvida hacerlo, puede
confundir a MQ en cuanto a qué parches se han aplicado.

\section{Otras herramientas para trabajar con parches}
\label{sec:mq:tools}

Cuando haya trabajado por cierto tiempo con parches, deseará
herramientas que le ayuden a entender y manipular los parches con los
que esté tratando.

La orden \command{diffstat}~\cite{web:diffstat} genera un histograma
de modificaciones hechas a cada fichero en un parche.  Provee una
interesante forma de ``dar un vistazo'' al parche---qué ficheros
afecta, y cuántos cambios introduce a cada fichero y en total.  (Me ha
parecido interesante usar la opción \cmdopt{diffstat}{-p} de
\command{diffstat}, puesto que de otra forma intentará hacer cosas
inteligentes con prefijos de ficheros que terminan confundiéndome.)

\begin{figure}[ht]
  \interaction{mq.tools.tools}
  \caption{Las órdenes \command{diffstat}, \command{filterdiff}, y \command{lsdiff}}
  \label{ex:mq:tools}
\end{figure}

El paquete \package{patchutils}~\cite{web:patchutils} es
invaluable. Provee un conjunto de pequeñas utilidades que siguen la
``filosofía Unix''; cada una hace una cosa muy bien hecha a un
parche. La orden \package{patchutils} que más uso es
\command{filterdiff}, que extrae subconjuntos de un fichero de
parche.  Por ejemplo, dado un parche que modifica centenas de ficheros
en docenas de directorios, una única invocación de
\command{filterdiff} puede generear un parche más pequeño que
solamente toca aquellos ficheros con un patrón.  Puede ver otro
ejemplo en la sección~\ref{mq-collab:tips:interdiff}.

\section{Buenas prácticas de trabajo con parches}

En caso de que esté trabajando en una serie de parches para enviar a
un proyecto de software libre o de fuentes abiertas, o en una serie
que desea tratar como un conjunto de cambios regular, cuando haya
terminado, puede usar técnicas sencillas para mantener su trabajo bien
organizado.

De nombres descriptivos a sus parches.  Un buen nombre para un parche
podría ser \filename{rework-device-alloc.patch}, porque da de forma
inmediata una pista del propósito del parche. Los nombres largos no
deben ser un problema; no los estará tecleando repetidamente, pero
\emph{estará} ejecutando regularmente órdenes como
\hgxcmd{mq}{qapplied} y \hgxcmd{mq}{qtop}.  Los nombres adecuados son
especialmente importantes cuando tiene bastantes parches con los
cuales trabajar, o si está trabajando en diferentes tareas y sus
parches toman solamente una porción de su atención.

Tenga en cuenta en qué parche está trabajando.  Use la orden \hgxcmd{mq}{qtop}
para dar un vistazo al texto de sus parches frecuentemente---por
ejemplo, use \hgcmdargs{tip}{\hgopt{tip}{-p}})---para asegurarse en
dónde está ubicado.  En distintas oportunidades me sucedió que apliqué
\hgxcmd{mq}{qrefresh} a un parche distinto al que deseaba hacerlo, y
usualmente es complejo migrar los cambios al parche correcto después
de haberlo hecho mal.

Por este motivo, vale la pena invertir ese poco tiempo para aprender
cómo usar otras herramientas que describí en la
sección~\ref{sec:mq:tools}, particularmente \command{diffstat} y
\command{filterdiff}.  La primera le dará una idea de qué cambios está
haciendo su parche, mientras que la segunda permite seleccionar trozos
de un parche para colocarlos en otro.

\section{Recetas de MQ}

\subsection{Administrar parches ``triviales''}

Puesto que colocar ficheros en un repositorio de Mercurial es tan
sencillo, tiene bastante sentido administrar parches de esta forma
incluso si desea hacer algunos cambios al paquete de ficheros que
descargó.

Para comenzar a descargar y desempaqueter un paquete de ficheros, y
volverlo en un repositorio de Mercurial:
\interaction{mq.tarball.download}

Continue creando una pila de parches y haga sus cambios.
\interaction{mq.tarball.qinit}

Digamos que pasan unas semanas o meses, y el autor del paquete libera
una nueva versión.  Primero se traen sus cambios al repositorio.
\interaction{mq.tarball.newsource}
La porción que comienza con \hgcmd{locate} mostrada más arriba, borra
todos los ficheros en el directorio de trabajo, así que la opción
\hgopt{commit}{--addremove} de \hgcmd{commit} puede indicar qué
ficheros se han eliminado en la nueva versión del árbol de fuentes.

Finalmente, puede aplicar sus parches encima del nuevo árbol de fuentes
\interaction{mq.tarball.repush}

\subsection{Combinar parches completos}
\label{sec:mq:combine}

MQ provee la orden \hgxcmd{mq}{qfold} que le permite combinar parches
enteros.  Se ``integran''\ndt{fold} los parches que usted nombre, en
el orden que especifique, en el último parche aplicado, y concatena
sus descripciones al final de su descripción.  Deberá sustraer los
cambios para poder integrarlos.

El orden en el que integre los parches importa.  Si el parche
últimamente aplicado es \texttt{foo}, e integra \hgxcmd{mq}{qfold} \texttt{bar} y
\texttt{quux} en él, terminará con un parche que tiene el mismo efecto
que si hubiera aplicado primero \texttt{foo}, y después \texttt{bar},
seguido de \texttt{quux}.

\subsection{Fusionar una porción de un parche dentro de otro}

Fusionar \emph{partes} de un parche dentro de otro es más complejo que
combinar completamente dos parches.

Si desea mover cambios de ficheros completos, puede usar las opciones
\command{filterdiff}'s \cmdopt{filterdiff}{-i} y
\cmdopt{filterdiff}{-x} para elegir las modificaciones remover de un
parche, concatenar su salida al final del parche donde desea
fusionarlo.  Usualmente no necesitará modificar el parche del cuál ha
fusionado los cambios.  En cambio, MQ reportará que hay unos trozos
que se han desechado cuando usted aplique \hgxcmd{mq}{qpush} (de los
trozos que haya movido al otro parche), y puede sencillamente aplicar
\hgxcmd{mq}{qrefresh} para eliminar los trozos replicados.

Si tiene un parche que tiene varios trozos que modifican un fichero, y
desea mover solamente unos de ellos, el trabajo es un poco más
enredado, pero puede automatizarlo parcialmente.  Use
\cmdargs{lsdiff}{-nvv} para imprimir algunos metadatos del parche.
\interaction{mq.tools.lsdiff}

Esta orden imprime tres clases diferentes de números:
\begin{itemize}
\item (en la primera columna) un \emph{número de fichero} para
  identificar cada fichero modificado en el parche;
\item (En la siguiente línea, indentado) el número de línea dentro de
  un fichero modificado donde comienza el trozo; y
\item (en la misma línea) un \emph{número de trozo} que identifica el
  trozo.
\end{itemize}

Tendrá que hacer una inspección visual, y leer el parche para
identificar los números de fichero y trozo que desea, pero puede pasar
posteriormente a las opciones \cmdopt{filterdiff}{--files} y 
\cmdopt{filterdiff}{--hunks} de \command{filterdiff}, para seleccionar
exactamente el fichero y el trozo que desea extraer.

Cuando tenga el trozo, puede concatenarlo al final de su parche
objetivo y continuar como en la sección~\ref{sec:mq:combine}.

\section{Diferencias entre quilt y MQ}

Si le es familiar quilt, MQ provee un conjunto similar de órdenes. Hay
algunas diferencias en cómo funcionan.

Debe haber notado que la mayoría de comandos de quilt tienen su
contraparte en MQ, que simplemente comienzan con ``\texttt{q}''.  Las
excepciones son las órdenes \texttt{add} y \texttt{remove} de quilt,
que realmente son las órdenes \hgcmd{add} y \hgcmd{remove} de
Mercurial.  No hay un equivalente en MQ para la orden
\texttt{edit} de quilt.

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "00book"
%%% End: 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.