Когда я познакомился с Mercurial, то все свои знания я почерпнул из статей Спольского (перевод на Хабре), которые подробно описывают основные принципы работы Mercurial и ежедневную работу с ним. Долгое время я использовал Mercurial в пределах, которые не превышали объема этих статей. Наверно, для одиночного разработчика этого почти достаточно. Почти. Но Mercurial сегодня значительно шире и обладает возможностями допускающими редактирование истории изменений, наличие которых, в общем-то, не очевидно, хотя возможности эти достаточно ценны. А из комментариев к разным статьям по системам управления версиями видно, что многие разработчики об этих возможностях не знают. Ниже я хочу провести обзор ряда возможностей Mercurial связанных с изменением истории.
О чем пойдет речь:
Ежедневная работа Mercurial заключается в создании новых наборов изменений (они же ревизии). Любой набор, как только он создан, навеки прописывается в репозитории. Неважно полезен ли этот отдельный набор, или он часть никому не нужной тупиковой ветви развития, он сохраняется и копируется во все репозитории. По крайней мере, так выглядит Mercurial на первый взгляд. С другой стороны иногда бывает действительно нужно удалять или заменять наборы изменений. Поэтому в Mercurial появился ряд инструментов, которые могут изменять историю. Изменять ревизии, которые известны другим репозиториям считается опасно, поскольку эти ревизии могут использоваться в других репозиториях, скажем, быть родителями новых ветвей. Поэтому удаление ревизий никогда не затрагивает внешние репозитории. Удаление локально. При синхронизации все ревизии, которые вы удалили у себя, будут вновь затянуты и создадут путаницу. Поэтому замена истории в Mercurial — это действие локального характера, которое проводиться только в пределах изменений, которых никто кроме вас не видит. Mercurial пытается автоматически отслеживать публичность или приватность наборов изменений при помощи механизма фаз.
Каждый набор изменений принадлежит к одной из трех фаз:
Итак, когда мы создаем новый набор изменений при помощи hg commit, этот набор относится к фазе draft. Этот набор есть только у нас, однако, при первой возможности все изменения будут отправлены в общий репозиторий. Фаза при этом изменится на public. Если мы хотим пока работать локально, чтобы об изменения не публиковались, то мы можем отнести изменения явно к фазе secret. Тогда изменения будут оставаться в локальном репозитории до тех пор, пока мы явно не изменим фазу на draft или public.
Проверяется и изменяется фаза командой hg phase. К примеру, возьмем репозиторий, в котором есть только один набор изменений:
Проверяем, какая сейчас фаза у набора изменений 0:
Чтобы изменить фазу к команде добавляется параметр –draft, --public или –secret (они же –d, -p, -s). Изменяем фазу на секретную:
Обратите внимание, что для того, чтобы увеличить фазу (в направлении от публичной до секретной) нужно использовать ключ --force. Уменьшение фазы в обратном направлении всегда безопасно. Чаще всего нужно только помечать наборы изменений как секретные, либо возвращать их к фазе draft. Механизм фазы задуман таким образом, чтобы не требовать особого внимания пользователя. Напоминаю, что изменять наборы изменений можно, только если они не принадлежат к публичной фазе.
Наверное, каждому случалось через мгновение после коммита обнаруживать ошибку в сообщении или сталкиваться с тем, что только что созданный коммит сломал билд. Как раз для этих случаев команда hg commit имеет опцию amend. Когда используется эта опция вместо создания отдельного набора изменений, вносится коррекция в последний из наборов (точнее в текущий набор). Все настолько просто, что рассказывать нечего. Создаем коммит с ошибкой в текстовом описании:
Замечаем оплошность и тут же исправляем ее:
Результат:
Изменяется не только описание. Можно вносить правки в исходники, и они добавятся в новый набор изменений. Из вывода команды можно заметить, что Mercurial сделал бакап, на случай если мы сделали какую-то глупость. Восстановить бакап можно командой hg unbundle. И еще добавлю: commit --amend работает только с наборами изменений, у которых нет дочерних элементов.
Commit --amend доступно всегда, а вот команды hg rebase и hg strip является стандартными расширениями, которые по умолчанию отключены. Чтобы включить расширения нужно добавить в файл Mercurial.ini (либо в файл .hg/hgrc, чтобы включить расширения только в отдельном репозитории) следующие строки:
Команда strip удаляет ревизию и всех ее потомков из репозитория:
Забавно, что команда strip удаляет, но не подменяет историю, поэтому ее допускается использовать с наборами изменений любой фазы. Однако если удалить наборы, которые засветились в других репозиториях, то при следующем затягивании изменений все удаления восстановятся.
Понять команду Rebase проще всего из примеров. Основная задача rebase – превратить две различные ветви в линейную историю.
Пока мы работали над веткой X, Y, Z, во внешнем репозитории возникли ревизии D, E.
Поскольку чужие изменения мы трогать не можем, мы можем перебазировать свои. Результат должен быть таким:
Локальные наборы изменений X, Y и Z удаляются (сохраняются в .hg/strip-backup, а вместо них вставляются аналогичные наборы изменений X2, Y2, Z2).
Rеbase делается следующей командой:
Есть и другие варианты использования команды. Сокращенное написание команды:
Использование --base вместо --source:
Когда применена опция --base, то Mercurial спускается от указанной ревизии до общего предка, за исключением самого общего предка. В нашем случае --base 6 означает то же, что и --source 4.
Если указать только одну из опций: base, source или dest, то вместо отсутствующего параметра используется текущая ревизия.
Опускаем опцию --dest, используем текущую ревизия в качестве dest.
Опускаем опции --source и --base, используем текущую ревизию в качестве base.
Несколько сценариев использования из документации Mercurial.
Простое перемещение ветви:
Пунктом назначения не обязательно должна быть конечная ревизия:
Немного более сложная структура:
Набор изменений слияния F перестает существовать за ненадобностью.
Ревизия H удаляется, это ревизия слияния, а в результате работы rebase все наборы и так уже содержат все нужные изменения.
Удаляются ревизии слияния D и H.
Иногда все изменения нужно вместить в одну ревизию. Для этого у команды rebase есть опция --сollapse.
Небольшая автоматизация, которая автоматически запускает rebase каждый раз при затягивании изменений. Результат стремиться к тому, чтобы все локальные изменения нарастились к затянутой снаружи ветке. Это не всегда срабатывает, но если срабатывает, то экономиться лишнее слияние.
О чем пойдет речь:
- фазы
- hg commit –amend
- hg strip
- hg rebase
Локальность изменения истории
Ежедневная работа Mercurial заключается в создании новых наборов изменений (они же ревизии). Любой набор, как только он создан, навеки прописывается в репозитории. Неважно полезен ли этот отдельный набор, или он часть никому не нужной тупиковой ветви развития, он сохраняется и копируется во все репозитории. По крайней мере, так выглядит Mercurial на первый взгляд. С другой стороны иногда бывает действительно нужно удалять или заменять наборы изменений. Поэтому в Mercurial появился ряд инструментов, которые могут изменять историю. Изменять ревизии, которые известны другим репозиториям считается опасно, поскольку эти ревизии могут использоваться в других репозиториях, скажем, быть родителями новых ветвей. Поэтому удаление ревизий никогда не затрагивает внешние репозитории. Удаление локально. При синхронизации все ревизии, которые вы удалили у себя, будут вновь затянуты и создадут путаницу. Поэтому замена истории в Mercurial — это действие локального характера, которое проводиться только в пределах изменений, которых никто кроме вас не видит. Mercurial пытается автоматически отслеживать публичность или приватность наборов изменений при помощи механизма фаз.
Фазы
Каждый набор изменений принадлежит к одной из трех фаз:
- если набор изменений уже был куда-то отправлен, либо получен из внешнего репозитория, то его фаза public (публичная), изменять набор нельзя.
- если набор создан локально, и никуда еще не отправлялся, то его фаза draft (черновик), изменять пока можно, однако при первой возможности (push или внешний pull) набор будет опубликован и станет public.
- если мы не хотим, чтобы набор стал публичным, то мы можем вручную отнести его к фазе secret (секретная). Такой набор будет опубликован, только если вручную вернуть его фазу на draft или public. Изменять набор можно смело.
Итак, когда мы создаем новый набор изменений при помощи hg commit, этот набор относится к фазе draft. Этот набор есть только у нас, однако, при первой возможности все изменения будут отправлены в общий репозиторий. Фаза при этом изменится на public. Если мы хотим пока работать локально, чтобы об изменения не публиковались, то мы можем отнести изменения явно к фазе secret. Тогда изменения будут оставаться в локальном репозитории до тех пор, пока мы явно не изменим фазу на draft или public.
Проверяется и изменяется фаза командой hg phase. К примеру, возьмем репозиторий, в котором есть только один набор изменений:
hg log
changeset: 0:adfd3246d8b4
tag: tip
user: Пользователь
date: Sat Nov 07 11:12:43 2015 +0300
summary: initial commitПроверяем, какая сейчас фаза у набора изменений 0:
hg phase -r 0
0: draft
Чтобы изменить фазу к команде добавляется параметр –draft, --public или –secret (они же –d, -p, -s). Изменяем фазу на секретную:
hg phase --secret –-force -r 0
hg phase -r 0
0: secret
Обратите внимание, что для того, чтобы увеличить фазу (в направлении от публичной до секретной) нужно использовать ключ --force. Уменьшение фазы в обратном направлении всегда безопасно. Чаще всего нужно только помечать наборы изменений как секретные, либо возвращать их к фазе draft. Механизм фазы задуман таким образом, чтобы не требовать особого внимания пользователя. Напоминаю, что изменять наборы изменений можно, только если они не принадлежат к публичной фазе.
то же самое в TortoiseHg
Фазу видно из главного окна TortoiseHg. изменить ее можно при помощи контекстного меню.
Commit --amend
Наверное, каждому случалось через мгновение после коммита обнаруживать ошибку в сообщении или сталкиваться с тем, что только что созданный коммит сломал билд. Как раз для этих случаев команда hg commit имеет опцию amend. Когда используется эта опция вместо создания отдельного набора изменений, вносится коррекция в последний из наборов (точнее в текущий набор). Все настолько просто, что рассказывать нечего. Создаем коммит с ошибкой в текстовом описании:
hg commit -m "Првый коммит"
Замечаем оплошность и тут же исправляем ее:
hg commit -m "Первый коммит" --amend
saved backup bundle to D:\work\Habr\hg1\.hg\strip-backup/54b061ad6202-amend-backup.hg
Результат:
hg log
changeset: 0:88779cfe79c1
tag: tip
user: Пользователь
date: Sat Nov 07 11:12:43 2015 +0300
summary: Первый коммит
Изменяется не только описание. Можно вносить правки в исходники, и они добавятся в новый набор изменений. Из вывода команды можно заметить, что Mercurial сделал бакап, на случай если мы сделали какую-то глупость. Восстановить бакап можно командой hg unbundle. И еще добавлю: commit --amend работает только с наборами изменений, у которых нет дочерних элементов.
то же самое в TortoiseHg
Для начала нужно TortoiseHg переключить режим фиксации. После этого кнопка «Фиксировать» получит название «Отмена» (Перевод сбивает с толку. По смыслу должно быть «Перефиксировать»). При ее нажатии будет запускаться commit --amend со всеми плюшами – можно изменить сообщение, можно исправить ошибки в файлах.
Для начала нужно TortoiseHg переключить режим фиксации. После этого кнопка «Фиксировать» получит название «Отмена» (Перевод сбивает с толку. По смыслу должно быть «Перефиксировать»). При ее нажатии будет запускаться commit --amend со всеми плюшами – можно изменить сообщение, можно исправить ошибки в файлах.
Включаем расширения
Commit --amend доступно всегда, а вот команды hg rebase и hg strip является стандартными расширениями, которые по умолчанию отключены. Чтобы включить расширения нужно добавить в файл Mercurial.ini (либо в файл .hg/hgrc, чтобы включить расширения только в отдельном репозитории) следующие строки:
[extensions]
rebase =
strip =
то же самое в TortoiseHG
Strip
Команда strip удаляет ревизию и всех ее потомков из репозитория:
hg strip 8
saved backup bundle to D:\work\Habr\hg0\.hg\strip-backup/92f6544e0370-backup.hg
Забавно, что команда strip удаляет, но не подменяет историю, поэтому ее допускается использовать с наборами изменений любой фазы. Однако если удалить наборы, которые засветились в других репозиториях, то при следующем затягивании изменений все удаления восстановятся.
Rebase
Понять команду Rebase проще всего из примеров. Основная задача rebase – превратить две различные ветви в линейную историю.
Пока мы работали над веткой X, Y, Z, во внешнем репозитории возникли ревизии D, E.
Поскольку чужие изменения мы трогать не можем, мы можем перебазировать свои. Результат должен быть таким:
Локальные наборы изменений X, Y и Z удаляются (сохраняются в .hg/strip-backup, а вместо них вставляются аналогичные наборы изменений X2, Y2, Z2).
Rеbase делается следующей командой:
hg rebase --source 4 --dest 8
saved backup bundle to D:\work\Habr\hg0\.hg\strip-backup/1ab1a1cc3d8d-backup.hg
Есть и другие варианты использования команды. Сокращенное написание команды:
hg rebase -s 4 -d 8
Использование --base вместо --source:
hg rebase --base 6 --dest 8
Когда применена опция --base, то Mercurial спускается от указанной ревизии до общего предка, за исключением самого общего предка. В нашем случае --base 6 означает то же, что и --source 4.
Если указать только одну из опций: base, source или dest, то вместо отсутствующего параметра используется текущая ревизия.
Опускаем опцию --dest, используем текущую ревизия в качестве dest.
hg up 8
hg rebase --source 4
Опускаем опции --source и --base, используем текущую ревизию в качестве base.
hg up 4
hg rebase --dest 8
то же самое в TortoiseHg
Результат операции
Результат операции
Примеры для закрепления
Несколько сценариев использования из документации Mercurial.
Превращаем две ветви в одну
Простое перемещение ветви:
hg rebase --dest E --base C.
Сдвигаем начало ветви
Пунктом назначения не обязательно должна быть конечная ревизия:
hg rebase --dest D --base C.
Избавляемся от слияния
Немного более сложная структура:
hg rebase --dest C --source D.
Набор изменений слияния F перестает существовать за ненадобностью.
Еще более интересный случай
hg rebase --dest I --source D
Ревизия H удаляется, это ревизия слияния, а в результате работы rebase все наборы и так уже содержат все нужные изменения.
Полная линеаризация истории
hg rebase --dest I --source B
Удаляются ревизии слияния D и H.
Перенос другой ветви
hg rebase --dest B --source C
Перенос части другой ветви
hg rebase --dest I --source G
Коллапс
Иногда все изменения нужно вместить в одну ревизию. Для этого у команды rebase есть опция --сollapse.
hg rebase --dest B --base E –collapse
Pull --rebase
Небольшая автоматизация, которая автоматически запускает rebase каждый раз при затягивании изменений. Результат стремиться к тому, чтобы все локальные изменения нарастились к затянутой снаружи ветке. Это не всегда срабатывает, но если срабатывает, то экономиться лишнее слияние.
Ограничения
- Обычно линейная история предпочтительнее, чем сложный граф, содержащий множество слияний. Однако иногда во время слияния производится сложная ручная работа по разрешению конфликтов из двух наборов. После применения rebase результат этой работы сохраняется, но сама ревизия соответствующая слиянию исчезает и соответственно, нельзя проверить либо исправить ошибки, допущенные в результате ручного слияния.
- Как rebase, так и pull --rebase, дает ошибку, если в репозитории находятся незафиксированные изменения. Перед тем как пользоваться расширениями, нужно сделать что-либо из списка:
- зафиксировать изменения
- отменить изменения
- отложить изменения командой shelve/unshelve (сначала нужно включить расширение shelve)
hg shelve --name shelve_name_1 ... hg unshelve shelve_name_1
- отложить изменения при помощи группы команд
hg diff > somefile hg revert –a ... hg import –no-commit somefile
- отложить изменения при помощи среды TortoiseHg
- зафиксировать изменения
Другие возможности редактирования истории
- Расширение MQ. Позволяет редактировать историю, однако считается устаревшим и не рекомендуется к использованию, поскольку именно для замены MQ созданы команды rebase, strip, histedit, graft, commit –amend.
- Расширение HistEdit. Позволяет редактировать историю в ручном режиме, производя отдельные операции с отдельными наборами изменений.
- Расширение RebaseIf. Делает то же самое что и Rebase, но стремится сохранять нетривиальные слияния. Не входит в стандартную поставку Mercurial.
- Расширение Evolve. Экспериментальное расширение, которое добавляет еще больше команд по редактированию истории. Например: uncommit (отмена коммита), fold (объединение наборов изменений), prune (удаление наборов изменений из истории). Работа этих команд обеспечивается тем, что к каждому набору изменения присваивается маркер устаревания. Благодаря этому маркеру настоящего удаления наборов не происходит, наборы лишь помечаются как устаревшие. Это означает, что операции редактирования истории могут работать даже с наборами в публичной фазе. Расширение экспериментальное и не входит в стандартную поставку Mercurial.
- Команда hg graft. Вообще говоря, не изменяет историю, но делает нечто похожее. hg graft копирует изменения из одной ветви в другую, при этом в старой ветви изменения не удаляются. После работы команды появляется несколько дубликатов наборов.
ostapbender
«Правильнее» будет называть это не «изменением истории», а «решением, какая это история будет»: You are not «rewriting» history. You are deciding history.