perlgit

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• ОПИСАНИЕ
• КЛОНИРОВАНИЕ РЕПОЗИТОРИЯ
• РАБОТА С РЕПОЗИТОРИЕМ
  • Определение вашего статуса
  • Процесс создания патчей
  • Примечание о производных файлах
  • Очистка рабочей директории
  • Бисекция
  • Ветви тем и переписывание истории
  • Графты
• ДОСТУП НА ЗАПИСЬ В РЕПОЗИТОРИЙ GIT
  • Принятие патча
  • Сохранение изменений в blead
  • О слиянии и перебазировании
  • Сохранение изменений в версиях технического обслуживания
  • Использование ветки smoke-me для тестирования изменений

НАЗВАНИЕ

perlgit - Подробная информация о git и репозитории Perl

ОПИСАНИЕ

Этот документ предоставляет подробную информацию о использовании git для разработки Perl. Если вы просто хотите поработать с быстрым патчем, сначала ознакомьтесь с perlhack. Этот документ предназначен для регулярных участников Perl, включая тех, у кого есть доступ на запись в репозиторий git.

КЛОНИРОВАНИЕ РЕПОЗИТОРИЯ

Весь исходный код Perl хранится централизованно в репозитории Git на github.com.

Вы можете создать только для чтения копию репозитория, выполнив:

% git clone git://github.com/Perl/perl5.git perl

Это использует протокол git (порт 9418).

Если вы не можете использовать протокол git из-за файрволла, вы также можете клонировать через http:

% git clone https://github.com/Perl/perl5.git perl

РАБОТА С РЕПОЗИТОРИЕМ

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

% git branch
* blead

Использование переключателя -a для branch также отобразит отслеживаемые удаленные ветви в репозитории:

% git branch -a
* blead
  origin/HEAD
  origin/blead
...

Ветви, которые начинаются с "origin", соответствуют "git remote", из которого вы клонировали (он называется "origin"). Каждая ветвь на удаленном репозитории будет точно отслеживаться этими ветвями. Вы НИКОГДА не должны работать с этими отслеживаемыми удаленными ветвями. Вы всегда работаете только в локальной ветви. Локальные ветви могут быть настроены на автоматическое слияние (при pull) из указанной удаленной ветви. Это относится к ветви по умолчанию blead , которая будет настроена на слияние из удаленной отслеживаемой ветви origin/blead.

Вы можете посмотреть последние коммиты:

% git log

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

% git pull

Предполагая, что мы находимся на ветви blead сразу после pull, эта команда будет более или менее эквивалентна:

% git fetch
% git merge origin/blead

На самом деле, если вы хотите обновить локальный репозиторий, не затрагивая рабочую директорию, вы делаете:

% git fetch

И если вы хотите обновить удаленные отслеживаемые ветви для всех определённых удалённых репозиториев одновременно, вы можете сделать

% git remote update

Однако ни одна из последних двух команд не обновит вашу рабочую директорию, но обе обновят отслеживаемые удалённые ветви в вашем репозитории.

Чтобы создать локальную ветвь удалённой ветви:

% git checkout -b maint-5.10 origin/maint-5.10

Чтобы вернуться к blead:

% git checkout blead

Определение вашего статуса

Самая часто используемая команда git, вероятно, будет

% git status

Эта команда выведет описание текущего состояния репозитория, включая изменённые файлы и неигнорируемые неотслеженные файлы, а также покажет, какие файлы подготовлены для следующего коммита, и обычно некоторую полезную информацию о том, как это изменить. Например, следующее:

% git status
On branch blead
Your branch is ahead of 'origin/blead' by 1 commit.

Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

      modified:   pod/perlgit.pod

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working
                                                             directory)

      modified:   pod/perlgit.pod

Untracked files:
  (use "git add <file>..." to include in what will be committed)

      deliberate.untracked

Это показывает, что изменения в этом документе подготовлены для коммита, и что в рабочей директории есть дополнительные изменения, ещё не подготовленные. Также показано, что в рабочей директории есть неотслеженный файл, и как вы можете видеть, показано, как это изменить. Также показано, что в рабочей ветви blead есть один коммит, который ещё не был отправлен на origin удалённый репозиторий. ПРИМЕЧАНИЕ: Этот вывод также отображается в качестве шаблона, если вы не предоставите сообщение для git commit.

Процесс создания патчей

Сначала прочитайте perlhack для получения подробностей о работе с ядром Perl. В этом документе описываются многие детали о том, как создать хороший патч.

Если у вас уже есть репозиторий Perl, убедитесь, что вы находитесь на ветке blead, и ваш репозиторий обновлён:

% git checkout blead
% git pull

Предпочтительно создавать патчи по отношению к последней версии blead, так как именно здесь происходит разработка новых изменений, за исключением критически важных исправлений ошибок. Критически важные исправления ошибок должны создаваться по отношению к соответствующим ветвям технического обслуживания или должны быть представлены с примечанием, указывающим все ветви, где исправление должно быть применено.

Теперь, когда всё обновлено, нам нужно создать временную новую ветвь для этих изменений и переключиться в неё:

% git checkout -b orange

Это сокращённая форма

% git branch orange
% git checkout orange

Создание ветви темы упрощает для администраторов перебазирование или слияние обратно в основную ветвь blead для более линейной истории. Если вы не работаете в ветви темы, администратор должен вручную использовать cherry-pick для применения ваших изменений к blead.

Это вызовет нарекания на perl5-porters, так что не делайте этого. Будьте крутыми.

Затем внесите свои изменения. Например, если Леон Брокаард изменит своё имя на Оранжевый Брокаард, мы должны изменить его имя в файле AUTHORS:

% perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS

Вы можете увидеть, какие файлы изменены:

% git status
On branch orange
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

   modified:   AUTHORS

И вы можете увидеть изменения:

% git diff
diff --git a/AUTHORS b/AUTHORS
index 293dd70..722c93e 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -541,7 +541,7 @@    Lars Hecking              <lhecking@nmrc.ucc.ie>
 Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
 Leif Huhn                      <leif@hale.dkstat.com>
 Len Johnson                    <lenjay@ibm.net>
-Leon Brocard                   <acme@astray.com>
+Orange Brocard                 <acme@astray.com>
 Les Peters                     <lpeters@aol.net>
 Lesley Binks                   <lesley.binks@gmail.com>
 Lincoln D. Stein               <lstein@cshl.org>

Теперь сохраните свои изменения локально:

% git commit -a -m 'Rename Leon Brocard to Orange Brocard'
Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
 1 files changed, 1 insertions(+), 1 deletions(-)

Вариант -a используется для включения всех отслеживаемых git файлов, которые вы изменили. Если в данный момент вы хотите сохранить только некоторые из файлов, над которыми вы работали, вы можете опустить -a и использовать команду git add FILE ... перед выполнением коммита. git add --interactive позволяет даже сохранять части файлов вместо всех изменений в них.

Вариант -m используется для указания сообщения коммита. Если вы его опустите, git откроет текстовый редактор для составления сообщения интерактивно. Это полезно, когда изменения более сложны, чем приведённый здесь пример, и, в зависимости от редактора, чтобы знать, что первая строка сообщения коммита не превышает допустимого максимального значения в 50 символов. См. "Commit message" в perlhack для получения дополнительной информации о том, что делает сообщение коммита хорошим.

После завершения написания сообщения коммита и выхода из редактора git запишет ваше изменение в диск и скажет что-то вроде этого:

Created commit daf8e63: explain git status and stuff about remotes
 1 files changed, 83 insertions(+), 3 deletions(-)

Если вы снова выполните git status, вы увидите что-то вроде этого:

% git status
On branch orange
Untracked files:
  (use "git add <file>..." to include in what will be committed)

      deliberate.untracked

nothing added to commit but untracked files present (use "git add" to
                                                                 track)

В случае сомнений, прежде чем делать что-либо ещё, проверьте свой статус и внимательно прочитайте его, многие вопросы отвечаются непосредственно выводом git status.

Вы можете изучить свой последний коммит с помощью:

% git show HEAD

и если вы не довольны описанием или самим патчем, вы можете исправить его, снова отредактировав файлы, а затем выполните:

% git commit -a --amend

Теперь создайте форк на GitHub, чтобы отправить свою ветвь, и добавьте её как удалённый репозиторий, если вы этого ещё не сделали, как описано в документации GitHub по адресу https://help.github.com/en/articles/working-with-forks:

% git remote add fork git@github.com:MyUser/perl5.git

И отправьте ветвь в свой форк:

% git push -u fork orange

Теперь вы должны отправить запрос на слияние (PR) на GitHub из новой ветви в blead. Дополнительную информацию можно найти в документации GitHub по адресу https://help.github.com/en/articles/creating-a-pull-request-from-a-fork.

Вы также можете отправлять файлы патчей напрямую по адресу perl5-porters@perl.org, если патч ещё не готов к применению, но предназначен для обсуждения.

Чтобы создать файл патча для всех ваших локальных изменений:

% git format-patch -M blead..
0001-Rename-Leon-Brocard-to-Orange-Brocard.patch

Или для большого количества изменений, например, из ветви темы:

% git format-patch --stdout -M blead.. > topic-branch-changes.patch

Если вы хотите удалить свою временную ветвь, вы можете сделать это с помощью:

% git checkout blead
% git branch -d orange
error: The branch 'orange' is not an ancestor of your current HEAD.
If you are sure you want to delete it, run 'git branch -D orange'.
% git branch -D orange
Deleted branch orange.

Примечание о производных файлах

Помните, что многие файлы в дистрибутиве являются производными — избегайте их исправления, так как git не увидит в них изменений, а процесс сборки перепишет их. Исправляйте оригиналы вместо них. Большинство утилит (например, perldoc) относятся к этой категории, то есть исправьте utils/perldoc.PL, а не utils/perldoc. Точно так же не создавайте патчи для файлов в $src_root/ext из их копий, найденных в $install_root/lib. Если вы не уверены в правильном расположении файла, который, возможно, был скопирован во время сборки исходного дистрибутива, обратитесь к MANIFEST.

Очистка рабочей директории

Команда git clean с различными аргументами может использоваться как замена make clean.

Чтобы сбросить рабочую директорию в первоначальное состояние, вы можете сделать:

% git clean -dxf

Однако помните, что это удалит ВСЕ неотслеженные данные. Вы можете использовать

% git clean -Xf

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

Если вы хотите только отменить некоторые неизменённые изменения, вы можете использовать git checkout и указать список файлов для отката или git checkout -f для отката всех из них.

Если вы хотите отменить один или несколько коммитов, вы можете использовать git reset.

Бисекция

git предоставляет встроенный способ определения коммита, который должен быть виновником возникновения данной ошибки. git bisect выполняет бинарный поиск истории, чтобы найти первый коммит, вызвавший сбой. Он быстрый, мощный и гибкий, но требует некоторой настройки и для автоматизации процесса необходима вспомогательная оболочечная сценарий.

Ядро предоставляет программу-обёртку, Porting/bisect.pl, которая пытается максимально упростить процесс бисекции, сделав его таким же простым, как выполнение Perl-однострочника. Например, если вы хотите узнать, когда это стало ошибкой:

perl -e 'my $a := 2'

вам просто нужно запустить это:

.../Porting/bisect.pl -e 'my $a := 2;'

Используя Porting/bisect.pl, с одной командой (и без других файлов) легко определить

• Какой коммит привёл к тому, что этот пример кода перестал работать?

• Какой коммит привёл к тому, что этот пример кода начал работать?

• Какой коммит добавил первый файл, соответствующий этому регулярному выражению?

• Какой коммит удалил последний файл, соответствующий этому регулярному выражению?

обычно без необходимости знать, какие версии Perl использовать в качестве начальной и конечной ревизий, так как Porting/bisect.pl автоматически ищет самую раннюю стабильную версию, для которой тест проходит. Запустите Porting/bisect.pl --help для получения полной документации, включая то, как настроить параметры Configure и времени компиляции.

Если вам нужна большая гибкость, чем предлагает Porting/bisect.pl, вам нужно запустить git bisect самостоятельно. Это наиболее полезно для автоматизации сборки и тестирования ревизий Perl. Для этого вам потребуется скрипт оболочки для git для тестирования конкретной ревизии. Пример скрипта — Porting/bisect-example.sh, который следует скопировать вне репозитория, так как процесс бисекции сбросит состояние до чистого коммита во время выполнения. В приведенных ниже инструкциях предполагается, что вы скопировали его как ~/run, а затем отредактировали его как требуется.

Сначала вы переходите в режим бисекции:

% git bisect start

Например, если ошибка присутствует в HEAD, но отсутствовала в 5.10.0, git узнает об этом, когда вы введёте:

% git bisect bad
% git bisect good perl-5.10.0
Bisecting: 853 revisions left to test after this

Это приводит к проверке коммита, являющегося медианой между HEAD и perl-5.10.0. Затем вы можете запустить процесс бисекции с помощью:

% git bisect run ~/run

Когда первый плохой коммит будет изолирован, git bisect об этом сообщит:

ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
Author: Dave Mitchell <davem@fdisolutions.com>
Date:   Sat Feb 9 14:56:23 2008 +0000

    [perl #49472] Attributes + Unknown Error
    ...

bisect run success

Вы можете просмотреть процесс бисекции с помощью git bisect log и git bisect visualize. git bisect reset выведет вас из режима бисекции.

Обратите внимание, что первое good состояние должно быть предком первого bad состояния. Если вы хотите найти коммит, который исправил какую-либо ошибку, вам нужно инвертировать свой тест-кейс (то есть завершать выполнение с 1 при успешном выполнении и 0 в противном случае) и по-прежнему указывать нижнюю границу как good и верхнюю как bad. «Первый плохой коммит» тогда следует понимать как «первый коммит, где ошибка была исправлена».

git help bisect содержит гораздо больше информации о том, как можно настроить двоичные поиски.

После бисекции вы можете настроить, скомпилировать и протестировать Perl в коммитах, определённых процессом бисекции. Иногда, особенно со старыми версиями Perl, make может завершиться неудачно в этом процессе. В этом случае вы можете исправить исходный код в точке старого коммита. Для этого следуйте рекомендациям, предоставленным в "Building perl at older commits" в perlhack.

Разветвления тем и переписывание истории

Отдельные разработчики должны создавать ветви тем под yourname/some_descriptive_name:

% branch="$yourname/$some_descriptive_name"
% git checkout -b $branch
... do local edits, commits etc ...
% git push origin -u $branch

Если вы работаете со старой версией Git (до 1.7), то git push не будет иметь переключателя -u, и вам нужно заменить последний шаг следующей последовательностью:

% git push origin $branch:refs/heads/$branch
% git config branch.$branch.remote origin
% git config branch.$branch.merge refs/heads/$branch

Если вы хотите внести изменения в ветвь темы другого разработчика, вы должны согласовать это с её создателем, прежде чем вносить любые изменения.

Иногда вы можете обнаружить, что исходный автор отредактировал историю ветви. Для этого есть множество хороших причин. Иногда автор просто перебазирует ветвь на более новую точку исходного кода. Иногда автор обнаружил ошибку в раннем коммите, которую он хотел исправить, прежде чем объединить ветвь в blead.

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

Единственный способ, которым вы сможете перебазировать или изменить историю отправленной ветви, — это удалить её и отправить как новую ветвь под тем же именем. Пожалуйста, хорошо обдумайте это. Возможно, лучше последовательно переименовать свои ветви, чтобы другим пользователям было проще перенести свои локальные изменения на новую версию. (XXX: требуется объяснение).

Если вы хотите перебазировать личную ветвь темы, вам придётся удалить существующую ветвь темы и отправить новую версию. Вы можете сделать это с помощью следующей формулы (см. объяснение refspec в документации по отправке Git для получения подробностей) после перебазирования своей ветви:

# first rebase
% git checkout $user/$topic
% git fetch
% git rebase origin/blead

# then "delete-and-push"
% git push origin :$user/$topic
% git push origin $user/$topic

ПРИМЕЧАНИЕ: на уровне репозитория запрещено удалять любые «основные» ветви. То есть любые ветви, соответствующие m!^(blead|maint|perl)!. Любая попытка сделать это приведёт к ошибке Git, подобной этой:

% git push origin :blead
*** It is forbidden to delete blead/maint branches in this repository
error: hooks/update exited with error code 1
error: hook declined to update refs/heads/blead
To ssh://perl5.git.perl.org/perl
 ! [remote rejected] blead (hook declined)
 error: failed to push some refs to 'ssh://perl5.git.perl.org/perl'

В соответствии с политикой мы не редактируем историю ветвей blead и maint-*. Если опечатка (или что-то худшее) проскользнёт в коммит blead или maint-*, мы исправим её в другом коммите. Единственные типы обновлений, разрешённые в этих ветвях, — это «прямые продолжения», где вся история сохраняется.

Аннотированные теги в каноническом репозитории perl.git никогда не будут удалены или изменены. Тщательно обдумайте, хотите ли вы отправить локальный тег в perl.git, прежде чем делать это. (Отправка простых тегов запрещена.)

Вставки

История Perl содержит одну ошибку, которая не была обнаружена при преобразовании: в истории было записано слияние между blead и maint-5.10, которое на самом деле не произошло. Из-за особенностей Git это сейчас невозможно исправить в публичном репозитории. Вы можете удалить это ошибочное слияние локально, добавив следующую строку в свой файл .git/info/grafts:

296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930

Эта строка вставки особенно важна, если выполняется бисекция в области интересующего «слияния».

Доступ на запись к репозиторию Git

После получения прав на запись вам потребуется изменить URL для удалённого репозитория origin для включения отправки. Отредактируйте .git/config с помощью команды git-config(1):

% git config remote.origin.url git@github.com:Perl/perl5.git

Вы также можете настроить своё имя пользователя и адрес электронной почты. Большинство людей делают это один раз глобально в своём файле ~/.gitconfig, выполнив что-то вроде:

% git config --global user.name "Ævar Arnfjörð Bjarmason"
% git config --global user.email avarab@gmail.com

Однако, если вы хотите переопределить это только для Perl, выполните что-то вроде следующего в perl:

% git config user.email avar@cpan.org

Также можно сохранить origin в качестве удалённого репозитория Git и добавить новый удалённый репозиторий для доступа по SSH:

% git remote add camel git@github.com:Perl/perl5.git

Это позволяет обновлять ваш локальный репозиторий, подтягивая изменения из origin, что быстрее и не требует аутентификации, и отправлять свои изменения обратно с помощью удалённого репозитория camel:

% git fetch camel
% git push camel

Команда fetch просто обновляет camel ссылки, так как сами объекты должны были быть скачаны при подтягивании изменений из origin.

Принятие исправления

Если вы получили файл исправления, сгенерированный с использованием вышеуказанного раздела, попробуйте применить его.

Сначала нам нужно создать временную новую ветвь для этих изменений и переключиться в неё:

% git checkout -b experimental

Исправления, отформатированные с помощью git format-patch , применяются с помощью git am:

% git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
Applying Rename Leon Brocard to Orange Brocard

Обратите внимание, что некоторые почтовые системы UNIX могут изменять текстовые вложения, содержащие «От ». Это исправит их:

% perl -pi -e's/^>From /From /' \
                       0001-Rename-Leon-Brocard-to-Orange-Brocard.patch

Если предоставлен только сырой diff, также можно использовать этот двухэтапный процесс:

% git apply bugfix.diff
% git commit -a -m "Some fixing" \
                           --author="That Guy <that.guy@internets.com>"

Теперь мы можем проверить изменения:

% git show HEAD
commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
Author: Leon Brocard <acme@astray.com>
Date:   Fri Dec 19 17:02:59 2008 +0000

  Rename Leon Brocard to Orange Brocard

diff --git a/AUTHORS b/AUTHORS
index 293dd70..722c93e 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -541,7 +541,7 @@ Lars Hecking                 <lhecking@nmrc.ucc.ie>
 Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
 Leif Huhn                      <leif@hale.dkstat.com>
 Len Johnson                    <lenjay@ibm.net>
-Leon Brocard                   <acme@astray.com>
+Orange Brocard                 <acme@astray.com>
 Les Peters                     <lpeters@aol.net>
 Lesley Binks                   <lesley.binks@gmail.com>
 Lincoln D. Stein               <lstein@cshl.org>

Если вы разработчик Perl и считаете, что исправление хорошее, вы можете объединить его в blead и затем отправить в основной репозиторий:

% git checkout blead
% git merge experimental
% git push origin blead

Если вы хотите удалить свою временную ветвь, вы можете сделать это с помощью:

% git checkout blead
% git branch -d experimental
error: The branch 'experimental' is not an ancestor of your current
HEAD.  If you are sure you want to delete it, run 'git branch -D
experimental'.
% git branch -D experimental
Deleted branch experimental.

Создание коммита в blead

Ветка 'blead' станет следующей производственной версией Perl.

Перед отправкой любых локальных изменений в blead крайне важно выполнить несколько действий, чтобы другие разработчики не пришли к вам с вилами и факелами:

• Убедитесь, что у вас есть хорошее сообщение о коммите. Подробнее см. "Commit message" в perlhack.

• Запустите тестовый набор. Вы можете подумать, что исправление одной опечатки не повлияет на файлы тестов. Вы ошибаетесь. Вот пример, где отсутствие запуска набора тестов вызвало проблемы. Было представлено исправление, которое добавило несколько тестов в существующий файл .t. Оно, безусловно, не должно повлиять ни на что другое, поэтому нет необходимости тестировать что-либо помимо одного затронутого файла .t, верно? Однако, адрес электронной почты отправителя изменился с момента последней отправки, и это привело к сбоям в других тестах. Запуск тестовой цели, указанной в следующем пункте, позволил бы выявить эту проблему.

• Если вы не запускаете весь набор тестов, то хотя бы запустите make test_porting. Это выполнит базовые проверки. Чтобы увидеть, какие проверки, посмотрите в t/porting.

• Если вы вносите какие-либо изменения, которые влияют на miniperl или ядровые функции, имеющие разные пути кода для miniperl, убедитесь, что вы запустите make minitest. Это позволит выявить проблемы, которые даже полный тестовый набор не обнаружит, поскольку он выполняет подмножество тестов в miniperl, а не в perl.

О слиянии и перебазировании

Простые одноразовые коммиты, отправленные в ветвь 'blead', должны быть простыми коммитами, которые применяются без проблем. Другими словами, вы должны убедиться, что ваша работа коммитится по отношению к текущему положению blead, чтобы вы могли отправить изменения в основной репозиторий без слияния.

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

To ssh://perl5.git.perl.org/perl.git
 ! [rejected]        blead -> blead (non-fast-forward)
error: failed to push some refs to 'ssh://perl5.git.perl.org/perl.git'
To prevent you from losing history, non-fast-forward updates were
rejected Merge the remote changes (e.g. 'git pull') before pushing
again.  See the 'Note about fast-forwards' section of 'git push --help'
for details.

В этом случае вы можете просто перебазировать свою работу по отношению к новому положению blead, как показано ниже (предполагается, что ваш удалённый репозиторий для основного репозитория — «p5p»):

% git fetch p5p
% git rebase p5p/blead

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

Для больших наборов коммитов, которые имеют смысл только вместе или которые будут полезны для резюме цели набора, вы должны использовать коммит слияния. Вы должны выполнять свою работу в ветви темы, которую вы регулярно перебазировываете относительно blead, чтобы убедиться, что ваш код не сломается из-за перемещения blead. Когда вы закончите свою работу, выполните окончательную перебазировку и тестирование. Линейная история теряется с каждым коммитом в blead, но окончательная перебазировка делает историю линейной снова, что облегчает будущим разработчикам понимание того, что произошло. Перебазируйте следующим образом (предполагается, что ваша работа была в ветви committer/somework):

% git checkout committer/somework
% git rebase blead

Затем можно слить его в мастер, как показано ниже:

% git checkout blead
% git merge --no-ff --no-commit committer/somework
% git commit -a

Переключатели выше заслуживают объяснения. --no-ff указывает, что даже если вся ваша работа может быть применена линейно к blead, все равно необходимо подготовить коммит слияния. Это гарантирует, что вся ваша работа будет представлена как отдельный ветвь, со всеми её коммитами, слитыми в основную ветвь blead с помощью коммита слияния.

--no-commit означает, что коммит слияния будет подготовлен, но не зафиксирован. Затем фиксируется непосредственно при выполнении следующей команды, которая откроет ваш редактор для описания коммита. Без --no-commit, коммит будет сделан практически без полезного сообщения, что значительно уменьшит ценность коммита слияния как заготовки для описания работы.

При описании коммита слияния, объясните цель ветви, и имейте в виду, что это описание, вероятно, будет использовано инженером выпуска при просмотре следующего документа perldelta.

Коммиты в версии поддержки

Версии поддержки должны изменяться только для добавления критических исправлений ошибок, см. perlpolicy.

Чтобы создать коммит в поддерживаемой версии perl, необходимо создать локальную ветвь отслеживания:

% git checkout --track -b maint-5.005 origin/maint-5.005

Это создаёт локальную ветвь с именем maint-5.005, которая отслеживает удалённую ветвь origin/maint-5.005. Затем можно выполнять pull, commit, merge и push, как и раньше.

Также можно использовать команду git cherry-pick для cherry-pick коммитов из blead и другой ветви. Рекомендуется использовать опцию -x к git cherry-pick для записи SHA1 исходного коммита в новое сообщение коммита.

Перед отправкой любых изменений в версию поддержки убедитесь, что вы выполнили шаги в "Выполнении коммитов в blead" выше.

Использование ветви smoke-me для тестирования изменений

Иногда изменения влияют на пути кода, которые невозможно протестировать на операционных системах, непосредственно доступных вам, и было бы разумно, если бы пользователи на других операционных системах протестировали изменения, прежде чем вы внесёте их в blead.

К счастью, есть способ протестировать ваши изменения на различных операционных системах: отправьте их в ветвь «smoke-me» и подождите, пока определённые автоматизированные тестеры не сообщают результаты с их операционных систем. Ветвь «smoke-me» определяется по имени ветви: в частности, на github.com это должна быть локальная ветвь, в первом элементе имени которой точно указано smoke-me.

Процедура примерно следующая (на примере ветви smoke-me tonyc под названием win32stat):

Сначала создайте локальную ветвь и переключитесь на неё:

% git checkout -b win32stat

Внесите изменения, скомпилируйте perl и протестируйте ваши изменения, затем зафиксируйте их в вашей локальной ветви. Затем отправьте вашу локальную ветвь в удалённую ветвь smoke-me:

% git push origin win32stat:smoke-me/tonyc/win32stat

Теперь вы можете переключиться обратно на blead локально:

% git checkout blead

и продолжить работу над другими задачами, ожидая день или два, следя за результатами, отчётами по вашей ветви smoke-me на http://perl.develop-help.com/?b=smoke-me/tonyc/win32state.

Если всё в порядке, обновите вашу ветвь blead:

% git pull

затем переключитесь на вашу ветвь smoke-me ещё раз и выполните rebase на blead:

% git rebase blead win32stat

Теперь переключитесь обратно на blead и слите вашу ветвь smoke-me в неё:

% git checkout blead
% git merge win32stat

Как описано ранее, если на вашей ветви smoke-me много изменений, то вы должны подготовить коммит слияния, в котором даётся общий обзор этих изменений, используя следующую команду вместо последней команды выше:

% git merge win32stat --no-ff --no-commit

Теперь вы должны скомпилировать perl и ещё раз протестировать (слитые) изменения (в идеале запустить весь набор тестов, но если это невозможно, по крайней мере запустить тесты t/porting/*.t) перед обычной отправкой ваших изменений:

% git push origin blead

Наконец, вам следует удалить удалённую ветвь smoke-me:

% git push origin :smoke-me/tonyc/win32stat

(что, вероятно, выведет предупреждение, которое можно проигнорировать:

remote: fatal: ambiguous argument
                                 'refs/heads/smoke-me/tonyc/win32stat':
unknown revision or path not in the working tree.
remote: Use '--' to separate paths from revisions

) и затем удалить вашу локальную ветвь:

% git branch -d win32stat