1 ---

     2 title: Changeset Evolution training

     3 author: |

     4   <span style="text-transform: none;"><small>Boris Feld<br/><a href="https://octobus.net">octobus.net</a></small></span>

     5 ---

     6 

     7 # Introduction

     8 

     9 ## Welcome

    10 

    11 Hello everyone, and welcome to this Changeset Evolution training. During this session, you will learn how to safely rewrite history with Mercurial and Evolve, and how to collaborate together with your colleagues while rewriting the history at the same time.

    12 

    13 This training is designed to last approximately ¾ hours.

    14 

    15 You will use this repository during the training: [https://bitbucket.org/octobus/evolve_training_repo](https://bitbucket.org/octobus/evolve_training_repo). Please clone it somewhere relevant.

    16 

    17 ```bash

    18 $ hg clone https://bitbucket.org/octobus/evolve_training_repo

    19 $ cd evolve_training_repo

    20 ```

    21 

    22 Copy the provided hgrc to ensure a smooth training experience:

    23 

    24 ```bash

    25 $ cp hgrc .hg/hgrc

    26 ```

    27 

    28 This training support will contains commands you are expected to type and launch. These commands will be in the following format:

    29 

    30 ```

    31 $ COMMAND YOU ARE EXPECTED TO TYPE

    32 output you are expecting to see

    33 ```

    34 

    35 ## Preliminary checks

    36 

    37 #### Mercurial version

    38 

    39 First let's use the following command to verify which version of Mercurial you are using:

    40 

    41 ```

    42 $ hg --version

    43 Mercurial Distributed SCM (version 4.4.2)

    44 (see https://mercurial-scm.org for more information)

    45 

    46 Copyright (C) 2005-2017 Matt Mackall and others

    47 This is free software; see the source for copying conditions. There is NO

    48 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

    49 ```

    50 

    51 You need at least Mercurial version `4.1`. If you don't have a recent enough version, please call your instructor.

    52 

    53 In order to activate the Evolve extension, add these lines in your user configuration (using the command `hg config --edit`):

    54 

    55 ```ini

    56 [extensions]

    57 evolve =

    58 topic =

    59 ```

    60 

    61 #### Mercurial extensions

    62 

    63 Now let's check the version of your extensions. You will need all of these for the training:

    64 

    65 ```

    66 $ hg --version --verbose

    67 [...]

    68   evolve       external  7.1.0

    69   topic        external  0.6.0

    70   rebase       internal

    71   histedit     internal

    72 ```

    73 

    74 # The Basics

    75 

    76 <!-- #### What is Changeset Evolution?

    77 

    78 With core Mercurial, changesets are permanent and history rewriting has been discouraged for a long time. You can

    79 commit new changesets to modify your source code, but you cannot

    80 modify or remove old changesets.

    81 

    82 For years, Mercurial has included various commands that allow

    83 history modification: ``rebase``, ``histedit``, ``commit --amend`` and so forth.

    84 However, there's a catch: until now, Mercurial's various mechanisms for

    85 modifying history have been *unsafe* and expensive, in that changesets were

    86 destroyed (“stripped”) rather than simply hidden and still easy to recover.

    87 

    88 Changeset Evolution makes things better by changing the behaviour of most existing

    89 history modification commands so they use a safer mechanism (*changeset

    90 obsolescence*, covered below) rather than the older, less safe *strip*

    91 operation.

    92 

    93 ``evolve`` is built on infrastructure in core Mercurial:

    94 

    95   * *Phases* (starting in Mercurial 2.1) allow you to distinguish

    96     mutable and immutable changesets.

    97 

    98   * *Changeset obsolescence* (starting in Mercurial 2.3) is how

    99     Mercurial knows how history has been modified, specifically when

   100     one changeset replaces another. In the obsolescence model, a

   101     changeset is neither removed nor modified, but is instead marked

   102     *obsolete* and typically replaced by a *successor*. Obsolete

   103     changesets usually become *hidden* as well. Obsolescence is a

   104     disabled feature in Mercurial until you start using ``evolve``.

   105 

   106  XXX More than just than obsolescence in core ? XXX

   107 

   108  XXX The part below is a bit overselling XXX

   109 

   110 Some of the things you can do with ``evolve`` are:

   111 

   112   * Fix a mistake immediately: “Oops! I just committed a changeset

   113     with a syntax error—I'll fix that and amend the changeset so no

   114     one sees my mistake.” (While this is possible using default

   115     features of core Mercurial, Changeset Evolution makes it safer.)

   116 

   117   * Fix a mistake a little bit later: “Oops! I broke the tests three

   118     commits back, but only noticed it now—I'll just update back to the

   119     bad changeset, fix my mistake, amend the changeset, and evolve

   120     history to update the affected changesets.”

   121 

   122   * Remove unwanted changes: “I hacked in some debug output two

   123     commits back; everything is working now, so I'll just prune that

   124     unwanted changeset and evolve history before pushing.”

   125 

   126   * Share mutable history with yourself: say you do most of your

   127     programming work locally, but need to test on a big remote server

   128     somewhere before you know everything is good. You can use

   129     ``evolve`` to share mutable history between two computers, pushing

   130     finely polished changesets to a public repository only after

   131     testing on the test server.

   132 

   133   * Share mutable history for code review: you don't want to publish

   134     unreviewed changesets, but you can't block every commit waiting

   135     for code review. The solution is to share mutable history with

   136     your reviewer, amending each changeset until it passes review.

   137 

   138   * Explore and audit the rewrite history of a changeset. Since Mercurial is

   139     tracking the edits you make to a changeset, you can look at the history of

   140     these edits. This is similar to Mercurial tracking the history of file

   141     edits, but at the changeset level. -->

   142 

   143 In this section, we are going to learn how to do basic history rewriting like rewriting a changeset or rebasing.

   144 

   145 ### Amend

   146 

   147 The smallest possible history rewriting is rewriting a changeset description message. We often save and close the editor too early, and/or haven't seen a typo.

   148 

   149 It is very easy to fix a changeset description message, so let's do that. First be sure that you are in your clone of the `evolve_training_repo`. then update to the `typo` branch:

   150 

   151 ```

   152 $ hg update typo

   153 ```

   154 

   155 Check what the current repository looks like:

   156 

   157 ~~~raw-file

   158 output/fix-a-bug-base.log

   159 ~~~

   160 

   161 ~~~graphviz-file

   162 graphs/fix-bug-1.dot

   163 ~~~

   164 

   165 We have a root commit and another based on it. Double-check that you are on the right changeset with the `hg summary` command:

   166 

   167 ~~~raw-file

   168 output/fix-a-bug-base-summary.log

   169 ~~~

   170 

   171 The current commit description message seems wrong, `Fx bug`, there is definitely a letter missing. Let's fix this typo with the `hg commit` command.

   172 

   173 Usually, the `hg commit` is used to create new commit but we can use the ``--amend`` option to instead modify the current commit (see `hg help commit` for more information):

   174 

   175 ~~~

   176 $ hg commit --amend --message "Fix bug"

   177 ~~~

   178 

   179 Let's take a look at the repository now:

   180 

   181 ~~~raw-file

   182 output/amend-after.log

   183 ~~~

   184 

   185 ~~~graphviz-file

   186 graphs/fix-bug-2.dot

   187 ~~~

   188 

   189 The logs before and after amending looks pretty similar, we are going to analyze the differences later. Did you catch the differences?

   190 

   191 ### Rebase

   192 

   193 <!-- XXX probably needs a sentence about the merge (Why do you want to avoid it) XXX -->

   194 

   195 Let's try to rebase something now. Let's say that you have a branch named `build/linuxsupport-v2` which was started on another branch named `build/v2`. Everything was fine until `build/v2` grew a new commit, and now you want to rebase `build/linuxsupport-v2` on top of `build/v2` to be up-to-date with other the changes:

   196 

   197 ```

   198 $ hg update build/linuxsupport-v2

   199 ```

   200 

   201 ~~~raw-file

   202 output/rebase-before.log

   203 ~~~

   204 

   205 ~~~graphviz-file

   206 graphs/rebase-before.dot

   207 ~~~

   208 

   209 <!-- XXX-REVIEW: Explain rebase CLI interface -->

   210 

   211 Let's rebase our branch on top of `build/v2` with the `hg rebase` command. The `hg rebase` command have many ways to select commits:

   212 

   213 1. Explicitly select them using "--rev".

   214 2. Use "--source" to select a root commit and include all of its descendants.

   215 3. Use "--base" to select a commit; rebase will find ancestors and their descendants which are not also ancestors of the destination.

   216 4. If you do not specify any of "--rev", "source", or "--base", rebase  will use "--base ." as above.

   217 

   218 For this first example, we are gonna stays simple and explicitly select the commits we want to rebase with the `--rev` option.

   219 

   220 The `hg rebase` command also accepts a destination with the ``--dest`` option. And finally, as we are using named branches, don't forget to use the `--keepbranches` or the rebased commits will be on the wrong branch:

   221 

   222 ~~~raw-file

   223 output/rebase.log

   224 ~~~

   225 

   226 Now we have a nice, clean and flat history:

   227 

   228 ~~~raw-file

   229 output/rebase-after.log

   230 ~~~

   231 

   232 ~~~graphviz-file

   233 graphs/rebase-after.dot

   234 ~~~

   235 

   236 For more details about how to use the `hg rebase` command, see `hg help rebase`.

   237 

   238 ### Under the hood

   239 

   240 What did happened when we just ran the `hg amend` and `hg rebase` commands? What was done exactly to make the whole process work seamlessly?

   241 

   242 Let's go back to our previous amend example.

   243 

   244 ##### Amend

   245 

   246 When we did our amend, the status of the repository was:

   247 

   248 ~~~raw-file

   249 output/behind-the-hood-amend-before-hash-hidden.log

   250 ~~~

   251 

   252 ~~~graphviz-file

   253 graphs/fix-bug-1.dot

   254 ~~~

   255 

   256 And after the amend, the repository looked like:

   257 

   258 ~~~raw-file

   259 output/behind-the-hood-amend-after.log

   260 ~~~

   261 

   262 ~~~graphviz-file

   263 graphs/fix-bug-2.dot

   264 ~~~

   265 

   266 Do you see what is the difference?

   267 

   268 The big difference, apart from the fixed changeset message, is the revision hash and revision number. The `Fix bug` revision changed from `d2eb2ac6a5bd` to `708369dc1bfe`. It means that the fixed changeset is a new one. But where did the old changeset go?

   269 

   270 It didn't actually go very far, as it just became **hidden**. When we rewrite a changeset with the Evolve extension, instead of blindly delete it, we create a new changeset and hide the old one, which is still there, and we can even see it with the `--hidden` option available on most Mercurial commands:

   271 

   272 ~~~raw-file

   273 output/under-the-hood-amend-after-log-hidden.log

   274 ~~~

   275 

   276 Notice the `x` in the log output which shows that a changeset is hidden.

   277 

   278 In addition to hiding the original changeset, we are also storing additional information which is recording the relation between a changeset, the **precursor** and its **successor**. It basically stores the information that the commit **X** was rewritten into the commit **Y** by the user **U** at the date **D**. This piece of information is stored in something called an **obsolescence marker**. It will be displayed like this:

   279 

   280 ~~~graphviz-file

   281 graphs/fix-bug-3.dot

   282 ~~~

   283 

   284 Here the commit **5d48a444aba7** was rewritten into **708369dc1bfe**. Also please notice the difference of style of the commit **5d48a444aba7**, that's because it have been rewritten.

   285 

   286 ##### Rebase

   287 

   288 **Successors** don't need to share anything with their **precursor**. They could have a different description message, user, date or even parents.

   289 

   290 Let's look at our earlier rebase example. The status before the rebase was:

   291 

   292 ~~~raw-file

   293 output/behind-the-hood-rebase-before-hash-hidden.log

   294 ~~~

   295 

   296 ~~~graphviz-file

   297 graphs/rebase-before.dot

   298 ~~~

   299 

   300 And after it was:

   301 

   302 ~~~raw-file

   303 output/behind-the-hood-rebase-after.log

   304 ~~~

   305 

   306 ~~~graphviz-file

   307 graphs/rebase-after.dot

   308 ~~~

   309 

   310 Did the same thing happen under the hood?

   311 

   312 Yes, exactly! The old changesets are still around, and they are just hidden.

   313 

   314 ~~~raw-file

   315 output/rebase-after-hidden.log

   316 ~~~

   317 

   318 And we created three **obsolescence markers**, between each rebased commit and its **successor**:

   319 

   320 ~~~graphviz-file

   321 graphs/rebase-after-hidden.dot

   322 ~~~

   323 

   324 ### Evolution History

   325 

   326 Mercurial is designed to track the history of files. Evolution goes beyond, and tracks the history of the history of files. It basically tracks the different versions of your commits.

   327 

   328 As it is a new dimension of history, the classical Mercurial commands are not always the best to visualize this new history.

   329 

   330 We have seen that we can see the **hidden** changesets with the `--hidden` option on `hg log`:

   331 

   332 ~~~raw-file

   333 output/under-the-hood-amend-after-log-hidden.log

   334 ~~~

   335 

   336 To visualize the **obsolescence history** of a particular changeset, we can use the dedicated command `hg obslog`. The option are quite similar to `hg log` (you can read `hg help obslog` for more information):

   337 

   338 ~~~raw-file

   339 output/under-the-hood-amend-after-obslog.log

   340 ~~~

   341 

   342 We can even print what changed between the two versions with the `--patch` option:

   343 

   344 ~~~raw-file

   345 output/under-the-hood-amend-after-obslog-patch.log

   346 ~~~

   347 

   348 Obslog works both ways, as it can display **precursors** and **successors** with the `--all` option:

   349 

   350 ```raw-file

   351 output/under-the-hood-amend-after-obslog-no-all.log

   352 ```

   353 

   354 ~~~raw-file

   355 output/under-the-hood-amend-after-obslog-all.log

   356 ~~~

   357 

   358 ~~~graphviz-file

   359 graphs/fix-bug-3.dot

   360 ~~~

   361 

   362 We can also use obslog on the changesets that we rebased earlier:

   363 

   364 ~~~raw-file

   365 output/under-the-hood-rebase-after-obslog.log

   366 ~~~

   367 

   368 Why the `hg obslog` command is only showing two commits while we rebased three of them?

   369 

   370 ```raw-file

   371 output/under-the-hood-rebase-after-obslog-branch.log

   372 ```

   373 

   374 And why the `hg obslog` command show disconnected graphs when asking for the obslog of the whole branch?

   375 

   376 ~~~graphviz-file

   377 graphs/rebase-after-hidden.dot

   378 ~~~

   379 

   380 While these two obsolescence logs look very similar —because they show a similar change—, the two changesets log histories looked quite different.

   381 

   382 Using the `hg log` command to understand the Evolution history is hard because it is designed for displaying the files history, not the Evolution history. The `hg obslog` has been specially designed for this use-case and is more suited for this use-case.

   383 

   384 #### TortoiseHG

   385 

   386 TortoiseHG should be able to display obsolescence history for your repositories.

   387 

   388 To display all the **hidden** commits, we need to click on the **search icon**, then on the **Show/Hide hidden changesets** at the right of the **filter** check box. It is also possible to provide a *revset* to filter the repository, for example `:6 + ::20` to display only the revisions we have been working with until now:

   389 

   390 ![](img/thg-obs.png)

   391 

   392 <!-- #### Deroulement

   393 

   394 Travail chacun de son côté pour apprendre à utiliser:

   395 

   396 - Réecriture de changeset

   397 - Affichage de l'obsolescence, log, obslog

   398 

   399 

   400 - Vérifier que chacun sait utiliser les commandes de base

   401 - Vérifier que chacun sait utiliser les commandes de visu, hg log, hg log -G, thg?

   402 => Pas trop longtemps // répartir

   403 

   404 - Créer un commit

   405 - Le amend sans evolve == bundle

   406 - Strip?

   407 - rebase sans evolve?

   408 - Why is it bad? exemple

   409 (Peut-etre pas leur faire pratiquer amend sans evolve, ca prends du temps)

   410 

   411 - With evolve, now

   412 - Activate it, check version

   413 - Amend with evolve

   414 - rebase with evolve

   415 

   416 - What happened?

   417 - View obs-history, hg log, obslog -->

   418 

   419 

   420 # Medium level

   421 

   422 ## More rewriting commands

   423 

   424 The `hg amend` and `hg rebase` commands are the foundations for changeset evolution in Mercurial. You could do everything with these, but, luckily for us, the evolve extension provides human-friendly commands for common needs. We are going to see them now:

   425 

   426 ### Amend

   427 

   428 The Evolve extension provides its own `hg amend` command, which is similar to the `hg commit --amend` that we used previously, and adds several nice features:

   429 

   430 - The `-e`/`--edit` option edits the commit message in an editor, which is not opened by default any more.

   431 - The user and date can be updated to the current ones with the `-U`/`--current-user` and `-D`/`--current-date` options.

   432 - More capabilities for rewriting the changeset.

   433 

   434 The `hg amend` command accepts either file paths, to add all the modifications on these files in the current changeset, or the `-i`/`--interactive` option to select precisely what to add in it.

   435 

   436 We are going to use it to rewrite the author of the changeset:

   437 

   438 ```

   439 $ hg update amend-extract

   440 ```

   441 

   442 We have two commits on the **amend-extract** branch:

   443 

   444 ```raw-file

   445 output/amend-extract-before.log

   446 ```

   447 

   448 The user for the **amend-extract** head seems wrong, so let's fix it with the `hg amend` command:

   449 

   450 ```raw-file

   451 output/amend-user.log

   452 ```

   453 

   454 Now let's check that the user has been amended correctly:

   455 

   456 ```raw-file

   457 output/amend-user-after-export.log

   458 ```

   459 

   460 The user is the good one, but the diff looks weird. It seems that both a bad file **and** an incorrect line have slipped in this commit. We need to fix that.

   461 

   462 There are several solutions here, and we could manually edit the file and amend it. But, luckily for us, the `hg amend` command also has a very helpful option named `--extract` that will help us.

   463 

   464 ### Amend extract

   465 

   466 The `hg amend` command is meant to move file modifications from your working directory to the current changeset (which is considered as the parent of working directory). `hg amend` also provides the option `--extract` that can be used to invert the meaning of the command: with this option, `hg amend` will move the file modifications from your current changeset to your working directory.

   467 

   468 This is often used to remove a file or a line that is not meant to be in the current commit.

   469 

   470 As usual, we can either pass file paths or use the `-i` option to select which lines to extract.

   471 

   472 First, let's extract the badfile:

   473 

   474 ```raw-file

   475 output/amend-extract-badfile.log

   476 ```

   477 

   478 Now let's check the status of the changeset and the working directory:

   479 

   480 ```raw-file

   481 output/amend-extract-badfile-after-export.log

   482 ```

   483 

   484 The file is not included in the commit anymore! Did it just vanish? What if you wanted to keep it and, for example, put it in another commit?

   485 

   486 Don't worry, the extracted files and lines still are in your working directory:

   487 

   488 ```raw-file

   489 output/amend-extract-badfile-after-status.log

   490 ```

   491 

   492 As we are not going to need this file anymore, let's forget it with the `hg revert` command:

   493 

   494 ```raw-file

   495 output/amend-extract-badfile-after-revert.log

   496 ```

   497 

   498 Also don't forget to remove the file:

   499 

   500 ```bash

   501 $ rm badfile

   502 ```

   503 

   504 Ok. Now we still have a line to extract from our commit, so let's use the handy interactive mode of `hg amend --extract` to extract lines:

   505 

   506 ```raw-file

   507 output/amend-extract.log

   508 ```

   509 

   510 Much better! One last thing, as the line that we extracted is still in our working directory, just like when we extracted a file:

   511 

   512 ```raw-file

   513 output/amend-extract-after-status.log

   514 ```

   515 

   516 ```raw-file

   517 output/amend-extract-after-diff.log

   518 ```

   519 

   520 Don't forget to revert the change, as we are not going to need it any more:

   521 

   522 ```raw-file

   523 output/amend-extract-after-revert.log

   524 ```

   525 

   526 Now let's take a look at the obsolescence history:

   527 

   528 ```raw-file

   529 output/amend-extract-after-obslog.log

   530 ```

   531 

   532 The obslog is read from bottom to top:

   533 

   534 - First we rewrite the user,

   535 - Then we extracted a whole file,

   536 - Then we extracted a line from a file

   537 

   538 We have made three changes that generated three **successors**.

   539 

   540 ```graphviz-file

   541 graphs/amend-extract-after-hidden.dot

   542 ```

   543 

   544 ### Fold

   545 

   546 Sometimes we want to group together several consecutive changesets. Evolve has a command for that: `hg fold`. First, let's update to the right branch:

   547 

   548 ```

   549 $ hg update fold

   550 ```

   551 

   552 Three changesets change the same file, and they could be folded together. This would make a cleaner and more linear history, and hide those pesky intermediate changesets:

   553 

   554 ```raw-file

   555 output/fold-before.log

   556 ```

   557 

   558 ```graphviz-file

   559 graphs/fold-before.dot

   560 ```

   561 

   562 We all have been in a similar situation. Let's make a nice and clean changeset with fold:

   563 

   564 ```raw-file

   565 output/fold.log

   566 ```

   567 

   568 That was easy!

   569 

   570 ```raw-file

   571 output/fold-after.log

   572 ```

   573 

   574 ```raw-file

   575 output/fold-after-hidden.log

   576 ```

   577 

   578 Can you imagine what the graphs will looks like?

   579 

   580 ```raw-file

   581 output/fold-after-hidden-obslog.log

   582 ```

   583 

   584 ```graphviz-file

   585 graphs/fold-after-hidden.log

   586 ```

   587 

   588 ### Split

   589 

   590 Sometimes you want to `fold` changesets together, and sometimes you want to `split` a changeset into several ones, because it is too big.

   591 

   592 ```

   593 $ hg update split

   594 ```

   595 

   596 Evolve also has a command for that, `hg split`:

   597 

   598 ```raw-file

   599 output/split-before.log

   600 ```

   601 

   602 ```graphviz-file

   603 graphs/split-before.dot

   604 ```

   605 

   606 Split accepts a list of revisions and will interactively ask you how you want to split them:

   607 

   608 ```raw-file

   609 output/split.log

   610 ```

   611 

   612 Now let's check the state of the repository:

   613 

   614 ```raw-file

   615 output/split-before-after.log

   616 ```

   617 

   618 ```graphviz-file

   619 graphs/split-before-after-hidden.dot

   620 ```

   621 

   622 It looks good. What about the obsolescence history?

   623 

   624 ```raw-file

   625 output/split-after-obslog.log

   626 ```

   627 

   628 ```raw-file

   629 output/split-after-obslog-all.log

   630 ```

   631 

   632 ### Prune

   633 

   634 After rewriting and rebasing changesets, the next common use case for history rewriting is removing a changeset.

   635 

   636 But we can't permanently remove a changeset without leaving a trace. What if other users are working with the changeset that we want to remove?

   637 

   638 The common solution is to mark the changeset as removed, and simulate the fact that it has been removed.

   639 

   640 This is why the Evolve extension is offering the `prune` command. Let's try to prune a changeset:

   641 

   642 ```

   643 $ hg update prune

   644 ```

   645 

   646 ```raw-file

   647 output/prune-before.log

   648 ```

   649 

   650 ```graphviz-file

   651 graphs/prune-before.dot

   652 ```

   653 

   654 `prune` is easy to use, just give it the revisions you want to prune:

   655 

   656 ```raw-file

   657 output/prune.log

   658 ```

   659 

   660 Now the changeset is not visible any more:

   661 

   662 ```raw-file

   663 output/prune-after.log

   664 ```

   665 

   666 But we can still access it with the `--hidden` option:

   667 

   668 ```raw-file

   669 output/prune-after-hidden.log

   670 ```

   671 

   672 The output of `obslog` changes a bit when displaying pruned changesets:

   673 

   674 ```raw-file

   675 output/prune-after-obslog.log

   676 ```

   677 

   678 ```graphviz-file

   679 graphs/prune-after-hidden.dot

   680 ```

   681 

   682 ### Histedit

   683 

   684 The `hg histedit` command is a power-user command. It allows you to edit a linear series of changesets, and applies a combination of operations on them:

   685 

   686 - 'pick' to [re]order a changeset

   687 - 'drop' to omit changeset

   688 - 'mess' to reword the changeset commit message

   689 - 'fold' to combine it with the preceding changeset (using the later date)

   690 - 'roll' like fold, but discarding this commit's description and date

   691 - 'edit' to edit this changeset (preserving date)

   692 - 'base' to checkout changeset and apply further changesets from there

   693 

   694 It's similar to the `git rebase -i` command.

   695 

   696 First, let's update to the right branch:

   697 

   698 ```

   699 $ hg update histedit

   700 ```

   701 

   702 ```raw-file

   703 output/histedit-before-log.log

   704 ```

   705 

   706 ```graphviz-file

   707 graphs/histedit-before.dot

   708 ```

   709 

   710 When launching the `hg histedit` command, an editor will show up with the following contents:

   711 

   712 ```raw-file

   713 output/histedit-no-edit.log

   714 ```

   715 

   716 Swap the first two lines with your text editor:

   717 

   718 ```raw-file

   719 output/histedit-commands.log

   720 ```

   721 

   722 Save and exit. Histedit will apply your instructions and finish.

   723 

   724 Let's see the state of the repository:

   725 

   726 ```raw-file

   727 output/histedit-after-log.log

   728 ```

   729 

   730 ```raw-file

   731 output/histedit-after-log-hidden.log

   732 ```

   733 

   734 ```graphviz-file

   735 graphs/histedit-after-hidden.dot

   736 ```

   737 

   738 <!-- #### Deroulement

   739 

   740 - prune with evolve

   741 

   742 - advanced commands

   743 - fold

   744 - split -->

   745 

   746 ## Stack

   747 

   748 ### Stack definition

   749 

   750 One big problem when working with a DVCS to identify and switch between the different features/bugfixes you are working on.

   751 

   752 ### Named branches

   753 

   754 One solution is to use **named branches**. Named branches are a battle-tested, long-supported solution in Mercurial. Basically, a branch name is stored inside each changeset.

   755 

   756 This solution has several advantages:

   757 

   758 - It's supported in all recent-ish Mercurial versions.

   759 - It's simple to use.

   760 - Most tools are supporting it.

   761 

   762 But it also has several disadvantages:

   763 

   764 - Branches do not disappear once they are merged. You need to explicitely close them with `hg commit --close-branch`.

   765 - Branches are lost when rebasing them without the `--keepbranches` option of the `hg rebase` command.

   766 - New branches needs to be explicitly pushed with the `--new-branch` option of the `hg push` command.

   767 

   768 We will use named branches for this training, but other solutions are possible, like [topics](https://www.mercurial-scm.org/doc/evolution/tutorials/topic-tutorial.html).

   769 

   770 <!-- #### Topics

   771  -->

   772 

   773 ### Stack

   774 

   775 The `topic` extension provides a command to show your current stack, no matter how you defined it. Let's try it on some changesets that we rewrote earlier:

   776 

   777 ```

   778 $ hg update typo

   779 ```

   780 

   781 ```raw-file

   782 output/stack-typo.log

   783 ```

   784 

   785 The stack output shows three important data:

   786 

   787 - First, which branch you are working on (a.k.a. the **current** branch).

   788 - Then, all the commits that you are currently working on, with the current one highlighted.

   789 - Finally, which commit your branch is based on (**b0**).

   790 

   791 This branch is not very interesting, so let's move to another one.

   792 

   793 ```

   794 $ hg update build/linuxsupport-v2

   795 ```

   796 

   797 ```raw-file

   798 output/stack-rebase.log

   799 ```

   800 

   801 This is more interesting, as now we can see all the three changesets grouped together in the same view. The stack view provides a nice and linear view, even if the changesets are not immediate neighbors.

   802 

   803 ### Stack movement

   804 

   805 There is an easy way to navigate in your stack, the `hg next` and `hg prev` commands:

   806 

   807 ```raw-file

   808 output/stack-rebase-prev-from-b3.log

   809 ```

   810 

   811 ```raw-file

   812 output/stack-rebase-stack-b2.log

   813 ```

   814 

   815 And now for the `hg next` command:

   816 

   817 ```raw-file

   818 output/stack-rebase-next-from-b2.log

   819 ```

   820 

   821 ```raw-file

   822 output/stack-rebase.log

   823 ```

   824 

   825 The stack view also displays nice and easy relative ids for these changesets. You can use theses ids in all commands, for example with the `hg export` command:

   826 

   827 ```raw-file

   828 output/stack-rebase-export-b1.log

   829 ```

   830 

   831 Or with the `hg update` command:

   832 

   833 ```raw-file

   834 output/stack-rebase-update-b2.log

   835 ```

   836 

   837 These ids are handy because you don't need to manipulate changeset ids or revision numbers: contrary to the latters, the formers won't be affected by history edition. They only depend on their order in the branch.

   838 

   839 ```raw-file

   840 output/stack-rebase-stack-b2.log

   841 ```

   842 

   843 ### Edit mid-stack

   844 

   845 Now that we are in the middle of a stack, let's try amending a commit. The current commit message ends with a dot `.`, and we want to remove it:

   846 

   847 ```raw-file

   848 output/stack-rebase-stack-b2.log

   849 ```

   850 

   851 ```raw-file

   852 output/edit-mid-stack.log

   853 ```

   854 

   855 The message `1 new orphan changesets` means that, by amending a changeset having a child, this child is now **unstable**, as we can see with the `hg stack` command:

   856 

   857 ```raw-file

   858 output/edit-mid-stack-after-stack.log

   859 ```

   860 

   861 `hg stack` tries to simplify the view for you. We have amended **b2**, and **b3**'s parent is the precursor version of **b2**, so it is not stable any more. It is now **orphan**.

   862 

   863 For once, let's use log to see in detail in which situation we are:

   864 

   865 ```raw-file

   866 output/edit-mid-stack-after-log.log

   867 ```

   868 

   869 ```graphviz-file

   870 graphs/edit-mid-stack-after.dot

   871 ```

   872 

   873 How can we resolve this situation? It is actually very easy, and we are going to see how in the next section.

   874 

   875 <!-- #### Deroulement

   876 

   877 Tout seul:

   878 

   879 - Topic? stack?

   880 

   881 - Comment définir ce sur quoi on travaille?

   882 

   883 - Solution possible: named branches

   884 - Avantages des branches nommées

   885 - Inconvénients des branches nommées

   886 

   887 - Solution possible: topic

   888 - Avantages des topic

   889 - Inconvénients des topic

   890 - Commands: hg stack, hg topics, hg topics --age, hg topics --verbose

   891 (Pas forcément topic, risque de confusion)

   892 

   893 - Visualiser une stack avec hg stack, hg show stack?

   894 - Se déplacer dans une stack avec hg prev/hg next

   895 

   896 - Editer au milieu d'une stac

   897 

   898 - Absorb? (Pas sous windows dur à installer) -->

   899 

   900 ## Basic instabilities + stabilization

   901 

   902 Instabilities are a normal step when using Evolve-powered workflows. Several tools are provided to fix them smoothly.

   903 

   904 #### Log

   905 

   906 First, let's clarify some vocabulary. An **obsolete** changeset is a changeset that has been rewritten. In the current stack, only one commit is `obsolete`:

   907 

   908 ```raw-file

   909 output/basic-stabilize-before-log-obsolete.log

   910 ```

   911 

   912 A changeset can also be **unstable**, meaning that it could be subject to one or more **instabilities**:

   913 

   914 * **orphan**, a changeset whose an ancestor is **obsolete**.

   915 * **content-divergent**, a changeset which has been rewritten in two different versions.

   916 * **phase-divergent**, a changeset which has been both rewritten and published.

   917 

   918 For the moment, we will only see the **orphan** instability. We can display the **instabilities** of a commit with the `{instabilities}` template keyword:

   919 

   920 ```raw-file

   921 output/basic-stabilize-before-log-instabilities.log

   922 ```

   923 

   924 Here we have also one **orphan** commit, which is the child of the **obsolete** commit.

   925 

   926 #### Evolve --list

   927 

   928 The `hg evolve` command has a `--list` option which can list all the instabilities of your repository.

   929 

   930 ```raw-file

   931 output/basic-stabilize-before-evolve-list.log

   932 ```

   933 

   934 #### TortoiseHG

   935 

   936 Tortoise HG also has a nice support for displaying the instabilities of your repository:

   937 

   938 ![](img/thg-mid-stack.png)

   939 

   940 If you want to filter to get a better view, you can use the *revset* `branch(build/linuxsupport-v2)`:

   941 

   942 ![](img/thg-mid-stack-filter.png)

   943 

   944 #### Stabilization using `hg next --evolve`

   945 

   946 ```raw-file

   947 output/edit-mid-stack-after-stack.log

   948 ```

   949 

   950 In our current situation, a simple solution to solve the instability is to use the `hg next` command with the `--evolve` option. It will update to the next changeset on the stack, and stabilize it if necessary:

   951 

   952 ```raw-file

   953 output/basic-stabilize-next-evolve.log

   954 ```

   955 

   956 Here, it just rebased our old version of `b3` on top of the new version of `b2`.

   957 

   958 And now `hg stack` shows us a clean view again:

   959 

   960 ```raw-file

   961 output/basic-stabilize-after-stack.log

   962 ```

   963 

   964 That's better!

   965 

   966 ```graphviz-file

   967 graphs/basic-stabilize-after-stack.dot

   968 ```

   969 

   970 <!-- #### hg evolve

   971 

   972 XXX-REVIEW: Later -->

   973 

   974 # Advanced

   975 

   976 ## Moving change from one commit to another

   977 

   978 Create two commits:

   979 

   980 - The first one create a new file, add some content in it.

   981 - The second one create another file and modify the first file.

   982 

   983 Now try to move the change on the first file present in the second commit back in the first commit so that the first commit contains all change on the first file and the second change contains all changes on the second file.

   984 

   985 ## Exchange

   986 

   987 Coming Soon™

   988 

   989 <!-- ## Exchange -->

   990 

   991 <!-- #### Obsolescence History Synchronization

   992 

   993 XXX Too theoritical (except first sentence maybe) XXX

   994 

   995 While obsolescence markers are already useful locally, they unlock their true power when they are exchanged. They are the piece of information that are fundamental to achieve the goal of synchronizing repositories state.

   996 

   997 If two people starts with the same repository and they each make some modifications, once exchanging all their obsolescence marker with their partner; they should have the same repository state.

   998 

   999 Given a repository state R, if user A creates obs-markers OBSA and user B creates obs-markers OBSB, `R + OBSA + OBSB = R + OBSB + OBSA`.

  1000 

  1001 This characteristic is the foundation to make people confident with their modification as they know that they will be able to synchronize with someone and have exactly the same state. XXX-REVIEW BOF

  1002 

  1003 #### When are exchanged obsolescence markers

  1004 

  1005 Obsolescence markers are exchanges during all usual exchange methods:

  1006 

  1007 - Obsolescence markers related to pushed heads are pushed during `hg push`.

  1008 - Obsolescence markers related to pulled heads are also pulled during `hg pull`.

  1009 - Obsolescence markers are included in bundles.

  1010 

  1011 New obsolescence markers are automatically applied, so after a `pull` some changesets could become obsolete as they have been rewritten by a new changeset you just pulled.

  1012 

  1013 XXX-REVIEW: Add example?

  1014 

  1015 The obsolescence markers only apply to draft changesets though.

  1016 

  1017 ###### Let's exchange obsmarkers

  1018 

  1019 Let's try to push and pull some obsolescence-markers, first copy your repository somewhere else, for example:

  1020 

  1021 ```raw-file

  1022 output/basic-exchange-clone.log

  1023 ```

  1024 

  1025 #### Phases

  1026 

  1027 XXX Too theoritical XXX

  1028 

  1029 There is a dimension that have been overlooked until now. **Phases**. What are phases? Phases is an information about a changeset status, a changeset could be in one phase at any time:

  1030 

  1031 * **draft**, the default phase a changeset is just after committing it. This phase denotes that the changeset is still a work in progress. It could be rewritten, rebased, splitted, folded or even pruned before it's considered finished. This state allow a changeset to evolve into another version.

  1032 * **public**, the phase a changeset is when it's considered finished. The changeset would likely have been reviewed, tested and even released when they are in this state. This state forbids any rewriting on changeset which are public.

  1033 * **secret**, this phase is for changesets that should never be shared. It could be local-only modifications for your environment or a way to commit credentials without sharing it outside. This state allow a changeset to be rewritten, like to be rebased on the most up-to-date head for example.

  1034 

  1035 Phase are about changesets but they are not part of the commit information, meaning that changing the phase of a changeset does not change it's changeset hash.

  1036 

  1037 These phases are ordered (public < draft < secret) and no changeset can be in

  1038 a lower phase than its ancestors. For instance, if a changeset is public, all

  1039 its ancestors are also public. Lastly, changeset phases should only be changed

  1040 towards the public phase.

  1041 

  1042 Changeset are created in the **draft** phase by default and move to the **public** phase in several scenarios.

  1043 

  1044 #### Phase movement

  1045 

  1046 The original scenario for **phases** is to permits local rewriting of changesets that have not been pushed. You create draft changesets, you test them locally, possibly amend them, rebased them or clean it then you push it to a server and they become **public** at this occasion.

  1047 

  1048 While this scenario is pretty sensible, not altering shared commit make a lot of problems disappears, move powerful workflows could be unlocked when decoupling the sharing part with the publishing part.

  1049 

  1050 By default, hg server are in **publishing** mode, meaning that:

  1051 

  1052 - all draft changesets that are pulled or cloned appear in phase public on the client.

  1053 

  1054 - all draft changesets that are pushed appear as public on both client and server.

  1055 

  1056 - secret changesets are neither pushed, pulled, or cloned.

  1057 

  1058 Hg servers could also be configured into **non-publishing** mode with this configuration:

  1059 

  1060 ```ini

  1061 [phases]

  1062 publish = False

  1063 ```

  1064 

  1065 When pushing to a **non-publishing** mode, draft changesets are not longer made **public** anymore, allowing people and teams to share unfinished works. This way, it's still possible to edit a changeset after sharing it, meaning that:

  1066 

  1067 - a changeset could be updated after it has been reviewed.

  1068 - a changeset could be updated after a Continuous Integration tool show that some tests on some platforms are broken.

  1069 - a changeset could be updated after a co-worker tried implementing another feature on top of it.

  1070 

  1071 #### Usual phase workflow

  1072 

  1073 While sharing unfinished works is powerful, move **draft** changeset to the **public** phase when pushing them to **publishing** server is powerful by its simplicity. Its easy to understand as **non-publishing** servers could be seen as work-in-progress while **publishing** servers is meant for public, finished work that you commit to never alter. XXX-REVIEW Bof

  1074 

  1075 The usual way of having both advantages is to have both a **non-publishing** server where developers push for sharing work and asking for review and another **non-publishing** server when ready changesets are pushed, marking them as **public**.

  1076 

  1077 This way the **publishing** repository will only contains **public** changesets while the **non-publishing** one will contains all the **public** changesets plus all the **drafts** changesets.

  1078 

  1079 #### Phase visualization

  1080 

  1081 Phase is not shown by default in `hg log`, but we can ask for it with the `{phase}` template:

  1082 

  1083 ```raw-file

  1084 output/split-after-log-phase.log

  1085 ```

  1086 

  1087 It's also possible to use `hg phase` to recover the phase of a revision(s):

  1088 

  1089 ```raw-file

  1090 output/split-after-phase.log

  1091 ```

  1092 

  1093 You might wondered why you saw different forms in the graphs before, that was the phase that were shown. From now on, public changesets will be shown as circles, drafts changesets will be shown as hexagons and secrets changesets will be shown as squares:

  1094 

  1095 ```graphviz-file

  1096 graphs/phases.dot

  1097 ```

  1098 

  1099 #### Phase selection

  1100 

  1101 Phase have a few revsets for selecting changesets by their phases:

  1102 

  1103 - `public()`, select all public changesets.

  1104 - `draft()`, select all draft changesets.

  1105 - `secrets()`, select all secret changesets.

  1106 

  1107 It could be used to:

  1108 

  1109 - select all non-public changesets with `hg log -r "not public()"`.

  1110 - change all secret changesets to draft with `hg phase --draft "secret()"`. -->

  1111 

  1112 <!-- #### Deroulement

  1113 

  1114 Toujours tout seul:

  1115 

  1116 - push / pull

  1117 - phases -->

  1118 

  1119 <!-- ## Advanced -->

  1120 

  1121 <!-- #### Deroulement

  1122 

  1123 Advances use-cases:

  1124 

  1125 - Move part of a changeset to another (split+fold) -->

  1126 

  1127 <!-- ## Let's start the fun -->

  1128 

  1129 <!-- #### Deroulement

  1130 

  1131 À deux:

  1132 

  1133 - troubles, divergence, orphan

  1134 - troubles visualization

  1135 - troubles resolution