git-svn

git-svn — Взаимодействие между хранилищем Subversion и Git

git svn — это простой инструмент для передачи изменений между Subversion и Git. Он обеспечивает двусторонний поток изменений между хранилищем Subversion и хранилищем Git.

git svn может отслеживать стандартное хранилище Subversion, следуя общему расположению «trunk/branches/tags», с помощью опции --stdlayout. Он также может отслеживать ветви и теги в любом расположении с помощью опций -T/-t/-b (см. опции для init ниже, а также команду clone).

После отслеживания хранилища Subversion (любым из перечисленных выше способов) хранилище Git может быть обновлено из Subversion с помощью команды fetch, а Subversion — из Git с помощью команды dcommit.

Поскольку параметры noMetadata, rewriteRoot, rewriteUUID, useSvnsyncProps и useSvmProps влияют на генерируемые и используемые метаданные git svn, они должны быть установлены в файле конфигурации до импорта любой истории, а эти настройки никогда не должны меняться после их установки.

Кроме того, только один из этих параметров может быть использован в каждом разделе svn-remote, потому что они влияют на строку метаданных git-svn-id:, за исключением rewriteRoot и rewriteUUID, которые могут быть использованы вместе.

Отслеживание и внесение изменений в ветку trunk проекта, управляемого Subversion (игнорирование тегов и ветвей):

# Clone a repo (like git clone):
        git svn clone http://svn.example.com/project/trunk
# Enter the newly cloned directory:
        cd trunk
# You should be on master branch, double-check with 'git branch'
        git branch
# Do some work and commit locally to Git:
        git commit ...
# Something is committed to SVN, rebase your local changes against the
# latest changes in SVN:
        git svn rebase
# Now commit your changes (that were committed previously using Git) to SVN,
# as well as automatically updating your working HEAD:
        git svn dcommit
# Append svn:ignore and svn:global-ignores settings to the default Git exclude file:
        git svn show-ignore >> .git/info/exclude

Отслеживание и внесение изменений в весь проект, управляемый Subversion (включая trunk, tags и branches):

# Clone a repo with standard SVN directory layout (like git clone):
        git svn clone http://svn.example.com/project --stdlayout --prefix svn/
# Or, if the repo uses a non-standard directory layout:
        git svn clone http://svn.example.com/project -T tr -b branch -t tag --prefix svn/
# View all branches and tags you have cloned:
        git branch -r
# Create a new branch in SVN
        git svn branch waldo
# Reset your master to trunk (or any other branch, replacing 'trunk'
# with the appropriate name):
        git reset --hard svn/trunk
# You may only dcommit to one branch/tag/trunk at a time.  The usage
# of dcommit/rebase/show-ignore should be the same as above.

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

# Do the initial import on a server
        ssh server "cd /pub && git svn clone http://svn.example.com/project [options...]"
# Clone locally - make sure the refs/remotes/ space matches the server
        mkdir project
        cd project
        git init
        git remote add origin server:/pub/project
        git config --replace-all remote.origin.fetch '+refs/remotes/*:refs/remotes/*'
        git fetch
# Prevent fetch/pull from remote Git server in the future,
# we only want to use git svn for future updates
        git config --remove-section remote.origin
# Create a local branch from one of the branches just fetched
        git checkout -b master FETCH_HEAD
# Initialize 'git svn' locally (be sure to use the same URL and
# --stdlayout/-T/-b/-t/--prefix options as were used on server)
        git svn init http://svn.example.com/project [options...]
# Pull the latest changes from Subversion
        git svn rebase

Предпочтительнее использовать git svn rebase или git rebase, а не git pull или git merge для синхронизации неинтегрированных коммитов с веткой git svn репозитория. Это сохранит историю неинтегрированных коммитов линейной относительно репозитория SVN и позволит использовать предпочтительную подкоманду git svn dcommit для отправки неинтегрированных коммитов обратно в SVN.

Изначально, git svn рекомендовал разработчикам выполнять pull или merge из ветки git svn. Это было связано с тем, что автор отдавал предпочтение git svn set-tree B для коммита единственного head вместо обозначения git svn set-tree A..B для коммита нескольких коммитов. Использование git pull или git merge с git svn set-tree A..B приведёт к сглаживанию нелинейной истории при коммите в SVN, и это может привести к тому, что коммиты слияния неожиданно отменят предыдущие коммиты в SVN.

Хотя git svn может отслеживать историю копирования (включая ветки и теги) для репозиториев, использующих стандартную структуру, он пока не может представлять историю слияний, произошедших внутри Git, для пользователей SVN. Поэтому рекомендуется, чтобы пользователи сохраняли историю как можно более линейной внутри Git, чтобы облегчить совместимость с SVN (см. раздел ПРЕДУПРЕЖДЕНИЯ ниже).

Если git svn настроен на извлечение ветвей (и --follow-branches активен), он иногда создаёт несколько ветвей Git для одной ветви SVN, где дополнительные ветви имеют имена вида branchname@nnn (где nnn - номер ревизии SVN). Эти дополнительные ветви создаются, если git svn не может найти родительский коммит для первого коммита в ветви SVN, чтобы связать ветвь с историей других ветвей.

Обычно первый коммит в ветви SVN представляет собой операцию копирования. git svn прочтёт этот коммит, чтобы получить номер ревизии SVN, из которой была создана ветвь. Затем он попытается найти коммит Git, соответствующий этой ревизии SVN, и использовать его в качестве родителя ветви. Однако возможно, что подходящего коммита Git в качестве родителя не будет. Это произойдёт, среди прочего, если ветвь SVN представляет собой копию ревизии, которая не была извлечена git svn (например, потому что это старая ревизия, которая была пропущена с --revision), или если в SVN был скопирован каталог, который не отслеживается git svn (например, ветвь, которая вообще не отслеживается, или подкаталог отслеживаемой ветви). В этих случаях git svn по-прежнему создаст ветвь Git, но вместо использования существующего коммита Git в качестве родителя ветви, он прочтёт историю SVN каталога, из которого была скопирована ветвь, и создаст соответствующие коммиты Git. Это обозначается сообщением «Инициализация родителя: <имя_ветви>».

Кроме того, он создаст специальную ветвь с именем <branchname>@<SVN-Revision>, где <номер_ревизии_SVN> - номер ревизии SVN, из которой была скопирована ветвь. Эта ветвь будет указывать на недавно созданный родительский коммит ветви. Если в SVN ветвь была удалена и затем повторно создана из другой версии, будет несколько таких ветвей с @.

Обратите внимание, что это может означать, что для одной ревизии SVN создаётся несколько коммитов Git.

Пример: в репозитории SVN со стандартной структурой trunk/tags/branches создаётся каталог trunk/sub в r.100. В r.200 trunk/sub разветвляется путём копирования в branches/. git svn clone -s затем создаст ветвь sub. Он также создаст новые коммиты Git для r.100 по r.199 и использует их в качестве истории ветви sub. Таким образом, для каждой ревизии с r.100 по r.199 будет два коммита Git (один для trunk/, один для trunk/sub/). Наконец, он создаст ветвь sub@200, указывающую на новый родительский коммит ветви sub (т.е. коммит для r.200 и trunk/sub/).

Для простоты и взаимодействия с Subversion рекомендуется, чтобы все пользователи git svn клонировали, извлекали и выполняли dcommit напрямую с сервера SVN и избегали всех операций git clone/pull/merge/push между репозиториями и ветвями Git. Рекомендуемый метод обмена кодом между ветвями Git и пользователями — git format-patch и git am, или просто выполнение 'dcommit' в репозиторий SVN.

Запуск git merge или git pull НЕ рекомендуется на ветви, из которой вы планируете dcommit , поскольку пользователи Subversion не могут увидеть какие-либо слияния, которые вы выполнили. Кроме того, если вы выполняете слияние или извлечение из ветки Git, которая является зеркалом ветки SVN, dcommit может выполнить коммит в неправильную ветку.

Если вы всё же выполняете слияние, обратите внимание на следующее правило: git svn dcommit будет пытаться выполнить коммит поверх SVN-коммита, указанного в

git log --grep=^git-svn-id: --first-parent -1

Вы must должны убедиться, что самый последний коммит ветви, в которую вы хотите выполнить dcommit, является first родительским коммитом слияния. В противном случае наступит хаос, особенно если первый родительский коммит — это более ранний коммит в той же ветке SVN.

git clone не клонирует ветви в иерархии refs/remotes или любые данные метаданных или конфигурации git svn. Таким образом, репозитории, созданные и управляемые с помощью git svn, должны использовать rsync для клонирования, если клонирование требуется.

Поскольку dcommit использует rebase внутри, любые ветви Git, которые вы git push до dcommit на, потребуют принудительной перезаписи существующей ссылки в удаленном репозитории. Это обычно считается плохой практикой, см. документацию git-push[1] для получения подробной информации.

Не используйте опцию --amend команды git-commit[1] для изменения, которое вы уже выполнили dcommit. Считается плохой практикой использовать --amend для коммитов, которые вы уже отправили в удаленный репозиторий другим пользователям, и dcommit с SVN аналогичен этому.

При клонировании репозитория SVN, если ни одна из опций для описания структуры репозитория не используется (--trunk, --tags, --branches, --stdlayout), git svn clone создаст репозиторий Git с полностью линейной историей, где ветви и теги отображаются как отдельные каталоги в рабочей копии. Хотя это самый простой способ получить копию всего репозитория, для проектов с множеством веток это приведёт к рабочей копии, значительно большей, чем просто trunk. Таким образом, для проектов, использующих стандартную структуру каталогов (trunk/branches/tags), рекомендуется клонировать с опцией --stdlayout. Если проект использует нестандартную структуру и/или ветки и теги не требуются, проще всего клонировать только один каталог (обычно trunk), не указывая никаких опций структуры репозитория. Если требуется полная история с ветками и тегами, необходимо использовать опции --trunk / --branches / --tags.

При использовании нескольких --branches или --tags, git svn не обрабатывает автоматически конфликты имён (например, если две ветки из разных путей имеют одинаковое имя или если ветка и тег имеют одинаковое имя). В этих случаях используйте init для настройки своего репозитория Git, а затем, перед первым fetch, отредактируйте файл $GIT_DIR/config таким образом, чтобы ветки и теги были связаны с различными именованными пространствами. Например:

branches = stable/*:refs/remotes/svn/stable/*
branches = debug/*:refs/remotes/svn/debug/*

git svn сохраняет информацию о конфигурации [svn-remote] в файле конфигурации репозитория $GIT_DIR/config. Она похожа на разделы [remote] ядра Git, за исключением того, что ключи fetch не принимают аргументы glob; вместо этого они обрабатываются ключами branches и tags. Поскольку некоторые SVN-репозитории имеют необычную конфигурацию с несколькими проектами, разрешены расширения glob, такие как перечисленные ниже:

[svn-remote "project-a"]
        url = http://server.org/svn
        fetch = trunk/project-a:refs/remotes/project-a/trunk
        branches = branches/*/project-a:refs/remotes/project-a/branches/*
        branches = branches/release_*:refs/remotes/project-a/branches/release_*
        branches = branches/re*se:refs/remotes/project-a/branches/*
        tags = tags/*/project-a:refs/remotes/project-a/tags/*

Обратите внимание, что подстановка * (звездочка) для локальной ссылки (справа от :) должна быть самой правой частью пути; однако, подстановка в удалённой ссылке может быть в любом месте, пока это независимая часть пути (окружённая / или EOL). Такой тип конфигурации не создаётся автоматически init и должен вводиться вручную с помощью текстового редактора или с помощью git config.

Также обратите внимание, что звездочка (*) разрешена только один раз на слово. Например:

branches = branches/re*se:refs/remotes/project-a/branches/*

сопоставит ветки release, rese, re123se, однако

branches = branches/re*s*e:refs/remotes/project-a/branches/*

вызовет ошибку.

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

[svn-remote "huge-project"]
        url = http://server.org/svn
        fetch = trunk/src:refs/remotes/trunk
        branches = branches/{red,green}/src:refs/remotes/project-a/branches/*
        tags = tags/{1.0,2.0}/src:refs/remotes/project-a/tags/*

Поддерживаются несколько ключей fetch, branches и tags:

[svn-remote "messy-repo"]
        url = http://server.org/svn
        fetch = trunk/project-a:refs/remotes/project-a/trunk
        fetch = branches/demos/june-project-a-demo:refs/remotes/project-a/demos/june-demo
        branches = branches/server/*:refs/remotes/project-a/branches/*
        branches = branches/demos/2011/*:refs/remotes/project-a/2011-demos/*
        tags = tags/server/*:refs/remotes/project-a/tags/*

Создание ветки в такой конфигурации требует разграничения места, которое следует использовать, используя флаги -d или --destination:

$ git svn branch -d branches/server release-2-3-0

Обратите внимание, что git-svn отслеживает максимальный номер ревизии, в котором появилась ветка или тег. Если подмножество веток или тегов изменяется после извлечения, то $GIT_DIR/svn/.metadata необходимо вручную отредактировать, чтобы удалить (или сбросить) branches-maxRev и/или tags-maxRev, как это необходимо.

Мы игнорируем все свойства SVN, кроме svn:executable. Любые необработанные свойства записываются в $GIT_DIR/svn/<refname>/unhandled.log

Переименованные и скопированные каталоги не распознаются Git и, следовательно, не отслеживаются при выполнении коммитов в SVN. Я не планирую добавлять поддержку этого, так как это довольно сложно и трудоёмко сделать работающим для всех возможных случаев (Git тоже этого не делает). Коммиты переименованных и скопированных файлов полностью поддерживаются, если они достаточно похожи, чтобы Git их распознал.

В SVN возможно (хотя и не рекомендуется) выполнить коммит изменений в тег (поскольку тег — это просто копия каталога, поэтому технически он такой же, как и ветка). При клонировании репозитория SVN, git svn не может знать, произойдёт ли такой коммит в тег в будущем. Таким образом, он действует консервативно и импортирует все теги SVN как ветки, добавляя префикс tags/ к имени тега.

git-rebase[1]