Как пользоваться darcs

Что такое darcs

darcs – это система контроля версий / репозиторий (англ: revision control system, version control system, repository). В наше время на репозиторий принято возлагать ответственность за:

• хранение старых версий файлов (например, для того, чтобы можно было вернуться к старой версии или подглядеть в ней что-то полезное); важная идея, которая вырастает из этого аспекта: так как для каждого файла, хранящегося в репозитории, есть старая версия, то мы всегда можем, не сомневаясь, удалять файлы или их части, которые нам мешают.
• создание истории изменений (пользователь программы иногда хочет посмотреть, что изменилось с того момента, как он скачал программу, и стоит ли ему озаботиться тем, чтобы обновить свою версию или ничего важного не изменилось)
• обмен изменениями между разработчиками и помощь в разрешении "конфликтов" (одновременных изменений одного и того же места двумя разработчиками)

Кроме darcs сегодня более-менее популярны системы хранения версий: git, svn (subversion), cvs, mercurial, bazaar, arch (он же tla). Из них git является безуловно наиболее развитой системой, но с ним несколько сложнее работать, чем с darcs, поэтому в курсе мы используем darcs. Несмотря на то, что каждая из этих систем декларирует, что построена на совершенно особых принципах (и это действительно так), все они предполагают почти идентичный порядок работы с ними, поэтому главное для начала обучиться работе с одной из них, тогда научиться работе с любой другой будет совсем несложно (фактически, достаточно будет узнать, как в другой системе называются десять основных команд).

Важно понимать, что репозиторий предназначен для хранения любых (желательно, текстовых) файлов, а не только программ (и уж точно не только программ на питоне). Например, в репозитории удобно писать текст статьи, особенно, если вы пишете статью в соавторстве.

Терминология

• рабочая директория (working directory) – директория (и её поддиректории) с файлами программы

• репозиторий (repository) – архив версий рабочей директории; история всех изменений

• изменение (patch; hunk) – разница между двумя версиями рабочей директории в архиве

Как подписывать изменения

• Изменения должны быть маленькими. Как правило: либо добавление одной новой фичи (или одной новой функции), либо исправление одной неисправности.

• Изменения нужно подписывать по-английски. darcs это особенно поощряет тем, что он плохо умеет работать с другими языками.

• Название должно в первую очередь отображать суть изменения. Например: added function fib или fixed fib: corrected interpretation of argument.

• Название должно быть коротким. Лучше, если оно будет укладываться букв в 50-60 (принято считать стандартным текстовым окном окно 80x24 букв – кроме основного описания изменения там должно уместиться ещё чуть-чуть информации). Это очень тяжёлое требование, зачастую трудно подобрать правильные слова, чтобы уложиться в такое ограничение. Но зато это делает сильно более читаемой историю изменений.

• К названию стоит прибавить указание файла, класса и функции, в которых произошли изменения. Одно название файла+класса+функции, то есть в изменении не должно меняться больше одной функции или одного класса.

• Если очень хочется указать связь с каким-то внешним перечнем чего-то, где было написано, что нужно делать (например, номер задания или tracker), это нужно делать примерно так:

  [task1] main.py: added function fib

  или

  [#37287] main.py: fixed fib: corrected interpretation of argument

  Такие пометки обозначают тем, кто знает, к чему относится изменение (а кому ещё нужно знать о таком соотношении?), а для остальных выглядят как безобидная абракадабра в скобках, которую глаз игнорирует.
• Длинные комментарии к изменениям (если вы справитесь с vi для того, чтобы написать их) нужны для одной из двух целей:

  1. Если изменение оказалось всё-таки не маленьким, для него нужно написать короткий (но ёмкий) заголовок и дальше в том же формате, который описан выше, перечислить куски изменения:

     Bugfixes:
      * main.py: fixed fib: corrected interpretation of argument
      * main.py: fixed invocation of fib

  2. Если короткое изменение требует подробных комментариев:

     main: security fix in fib
     
     In previous version user could gain root access by passing a large enough number and causing stack overflow.

Что стоит, что не стоит хранить в репозитории

• В репозитории безусловно стоит хранить все исходные коды программы, которые Вы пишете.
• Стоит хранить текстовые файлы с описаниями программы, подсказками, планами разработками и иже с ними.
• Стоит хранить вспомогательные скрипты: для запуска программы или для её сборки. (Ведь по сути эти скрипты тоже можно считать частью программы, которую Вы пишете).
• Не стоит хранить скомпилированные версии программ.
• Не стоит хранить файлы выдачи программы.
• Если входные данные программы не являются чем-то уникальным, разрабатываемым вместе с программой, их не стоит хранить в репозитории.
• В случае именно с darcs, который посредственно умеет работать с большими бинарными файлами, следует всякий раз основательно задуматься, прежде, чем класть в репозиторий что-нибудь бинарное (например, входные данные программы). Если такого рода данные всё-таки очень нужны, может лучше написать вспомогательный скрипт, который будет их добывать (из сети) или генерировать?

Пока Вы работаете в одиночку

Подготовка репозитория:

• создать репозиторий: зайти в директорию, где будут (или уже лежат) файлы проекта и сказать darcs init

• добавить файлы в репозиторий: darcs add имя_файла

  • если нужно добавить файлы поддиректории рабочей директории, нужно сначала добавить директорию, а уже потом сами файлы

• записать первую версию: darcs record – заодно darcs сразу спросит, каким именем Вы будете подписывать свои изменения

Собственно, работа:

• внести небольшое изменение (дописать одну функцию / исправить одну ошибку или группу логически связанных ошибок)

• записать изменение в репозиторий: darcs record

Полезные команды:

• darcs record -a – записать все изменения, не спрашивая по частям

• darcs mv откуда куда – гораздо лучше, чем сначала удалить файл из репозитория, затем вернуть его с другим именем

• darcs changes --last=10 – показать историю изменений

• darcs diff --last=3 – показать разницу текущего состояния рабочей директории с тем, что было три версии назад

• darcs revert – отказаться от части незаписанных изменений (сделать текущую версию рабочей директории более похожей на последнюю записанную)

• darcs whatsnew – показать незаписанные изменения

• darcs show contents -p "patch comment" имя_файла – показать старую версию файла

• darcs show contents -m 'date "2008-02-10 10:20:09"' имя_файла – показать ещё более старую (наверное) версию файла

• darcs help --match – как пользоваться флагом -m

• darcs tag – воткнуть в список версий рабочей директории закладку с подписью; обычно такие закладки символизируют завершение довольно большой части работы

• darcs help – подсказка про всё остальное

Когда вы работаете вдвоём

Сначала первый участник готовит репозиторий так же, как если бы он работал в одиночку. (Может так статься, что сначала он рассчитывал работать один и сделал кроме подготовки ещё и кучу работы – тем лучше!)

Когда новый участник подключается к разработке проекта:

• darcs get путь_к_репозиторию

  • путь_к_репозиторию может быть разным:

    • ~первыйучастник/Project

    • второйучастник@kodomo.fbb.msu.ru:~первыйучастник/Project – darcs будет пытаться выкачать репозиторий через SSH

    • http://kodomo.fbb.msu.ru/~первыйучастник/Project – darcs будет пытаться выкачать репозиторий через веб.

Теперь собственно работа стала чуть сложнее:

• перед началом работы получить последние новости от напарника: darcs pull (первому участнику в первый раз придётся сказать не darcs pull, а darcs pull путь_к_репозиторию_второго_участника)

• немного поредактировать (как и обычно)

• если участники не договорились о том, что они редактируют по очереди, то стоит ещё один раз сказать darcs pull непосредственно перед записью изменений в репозиторий – для упокою совести

• записать изменения в репозиторий: darcs record

На одном из darcs pull, если участники не договорились о разделении ответственности и редактируют одновременно (или если один из них не соблюдает правила, описанные в предыдущем абзаце), может случиться конфликт. Конфликт (conflict) – это когда darcs думает, что оба участника одновременно поправили одно и то же место в одном и том же файле. Обычно darcs в этом суждении не заблуждается. Если случился конфликт, то это самое место в этом самом файле будет размечено примерно так:

vvvvvvvvvvvvv
   print "Hello, world!"
-------------
   print "Hi, mom!"
^^^^^^^^^^^^^

Если такое случилось, нужно изучить этот фрагмент, понять, кто что сделал или хотя бы как правильно. (В этом поможет команда darcs whatsnew). Затем нужно убрать галочки, сделать правильную версию и снова попытаться сохранить полученное изменение в репозиторий.

Полезные ссылки

• Официальный сайт (там много полезного, но на английском): http://darcs.net/

• Русский краткий курс на официальном сайте http://wiki.darcs.net/DarcsWiki/ВведениеВDarcs