gEDA/gaf и git

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

Установка git и относящихся к нему инструментов

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

Для дистрибутивов, созданных на основе Debian: 

apt-get install git-core git-doc gitk stgit

Может быть также вам будет нужно сделать: 

apt-get install git-email git-completion

Fedora Linux: 

yum install git stgit

Изучение git

Главная страница документации git:

Руководство пользователя git:

Текущее руководство можно найти по ссылке:

Другие замечательные руководства/веб-страницы:

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

Анонимный доступ к репозиторию

Точная копия репозитория geda-gaf.git (или любого репозитория, поддерживаемого на git.geda-project.org) с использованием анонимного доступа git: 

git clone git://git.geda-project.org/geda-gaf.git

или 

git clone git://git.geda-project.org/pcb.git

Для других репозиториев, поддерживаемых на git.geda-project.org, просто измените последнюю часть вышеуказанной ссылки.

Для репозиториев различных проектов существует cgit-интерфейс. Обратиться к нему из браузера можно, набрав в строке адреса http://git.geda-project.org/ .

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

Для доступа в git с правами разработчика вам нужно связаться с DJ Delorie для установки вашего публичного ключа SSH, после этого для отправки своих изменений можно использовать следующие адреса: 

ssh://git@git.geda-project.org/geda-gaf.git

или 

ssh://git@git.geda-project.org/pcb.git

Вам также будет необходимо отредактировать свой файл ~/.ssh/config (создать его, если он не существует) и вставить туда следующий текст: 

Host git.geda-project.org
Port 65

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

Создание и внесение изменений

Настройка информации о пользователе

Вам нужно обеспечить наличие в вашем конфигурационном файле для git своего имени пользователя и адреса электронной почты. 

$ git config --global user.name "Здесь должно быть ваше имя"
$ git config --global user.email вы@ваш_домен.example.com

Внесение заплат других участников проекта

Если вы накладываете чью-нибудь заплату (например, из записи о заплате в launchpad), следует кое-что учесть. git сохраняет два имени и два адреса электронной почты для вносимого изменения: “автора” заплаты (“author”) и “вносящего” заплату (“committer”), так что при внесении изменений эти данные должны быть установлены правильно.

Прежде всего, проверьте, что:

Для простоты начните с немодифицированного неустаревшего дерева (git status не должен показывать никаких изменений).

Наложите заплату как обычно (как в примере): 

$ patch -p1 < example_changes.patch

Можно также использовать команду git apply: 

$ git apply example_changes.patch

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

Примечание: Допустить случайную ошибку очень легко, если ваш редактор заменяет пробелы знаками табуляции. Не разрешайте ему этого!

Прежде чем вносить изменения, git нужно проинформировать о каждом изменённом, добавленном или удалённом файле. Чтобы посмотреть, какие файлы изменены, запустите: 

$ git status

Для скорости, командой: 

$ git add -u

можно обновить все файлы, отслеживаемые git, включая удалённые.

Для добавления новых файлов, вносимых заплатой, используйте команду 

$ git add new_file.c

Примечание: параметры git add могут также задаваться и с помощью метасимволов.

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

$ git commit --author "Здесь должно быть имя автора <author@example.com>"

Альтернативно можно установить переменные окружения GIT_AUTHOR_NAME и GIT_AUTHOR_EMAIL перед обычным запуском команды git commit.

Написание хороших сообщений о внесении изменений

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

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

Не добавляйте перечень изменённых файлов в сообщения о внесении изменений. Эта информация очень просто добывается с помощью инструментария git.

Пример: 

Added new GedaList class derived from GObject

This abstracts a GList with API for write access. Its main use is in list
change notification, as it emits a "changed" g_signal when modified.
Read only access to the underlying GList is provided by an accessor,
currenly implemented as a macro.

Операция push - разрушительна

Предупреждение: добавление изменений с помощью push в удалённый репозиторий разрушительно

В отличие от CVS, командой git-push изменения не просто добавляются в основной репозиторий, но “продвигается” локальная версия. Всегда нужно дважды (или даже трижды) проверить, что “продвигаемые” вами изменения в самом деле предназначены для основного репозитория.

Как мне ... ?

Более подробную информацию можно найти в Руководстве по Git.

... получить копию репозитория gEDA/gaf git?

При анонимном доступе только на чтение: 

$ git clone git://git.geda-project.org/geda-gaf

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

$ git clone ssh://git@git.geda-project.org/geda-gaf

... поддерживать соответствие своей локальной копии текущей версии?

Те, кто не собирается отправлять свои изменения в центральный репозиторий git, могут запустить: 

$ git pull

Однако тем из вас, кто собирается “продвигать” свои изменения в центральный репозиторий git, использование git pull испортит историю сообщениями об объединении (“Merge branch 'master'”). Чтобы избежать этого, нужно запустить: 

$ git fetch
$ git rebase origin

... внести свои изменения в локальный репозиторий git?

$ git commit -a

Эта команда найдёт все изменённые файлы, о которых знает git (добавленные с помощью git-add) и запросит у вас сообщение о внесении изменений. Непременно следуйте указанному выше соглашению по написанию таких сообщений, если планируете отправлять свои изменения в центральный репозиторий.

Если вы хотите внести файлы из текущего каталога, или хотите внести только явно определённые файлы, не указывайте флаг -a и (или) укажите имена выбранных файлов в командной строке, например: 

$ git commit filename1 filename2

... отменить все невнесённые локальные изменения?

$ git checkout -f

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

... исправить/изменить моё последнее внесение изменений?

$ Редактирование каких-то файлов
$ git commit --amend filename1..filenameN

Этой командой все сделанные вами изменения собираются и повторно вносятся в репозиторий со старым сообщением.

... отслеживать ветку?

$ git checkout --track -b <локальное имя> origin/<удалённое имя>

Этой командой создаётся ветка <локальное имя>, которая отслеживает удалённую ветку <удалённое имя>.

... создать ветку (начиная с определённого тега)?

Запустите следующие команды (для примера используется ветка stable-1.4): 

 $ git branch stable-1.4 1.4.0-20080127
 $ git checkout stable-1.4
 <сделать изменения>
 $ git commit -a

Чтобы опубликовать эту ветку в центральном репозитории (требуется доступ в него на запись): 

 $ git push origin stable-1.4

... получить ветку разработки другого разработчика?

Кроме репозитория http://git.geda-project.org/, у нас есть его зеркало на http://repo.or.cz/w/geda-gaf.git. Некоторые разработчики имеют свои ответвления (fork) данного репозитория с ветками разработки новых возможностей.

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

  $ git fetch ссылка_на_репозиторий название_удалённой_ветки:название_локальной_ветки

Примеры: Получение ветки cairo_experiment от Peter C. выглядело бы так: 

  $ git fetch git://repo.or.cz/geda-gaf/pcjc2.git cairo_experiment:peters_cairo_experiment

Теперь вы можете переключиться на локальную копию ветки peters_cairo_experiment и поиграться с ней.

Возможно также добавить несколько удалённых ответвлений в локальный репозиторий: 

  $ git remote add <название> <url>
  $ git fetch <название>

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

  $ gitk --all

Примеры: 

  $ git remote add peter-b https://github.com/peter-b/geda-gaf.git
  $ git fetch peter-b
  $ git remote add gareth8118 https://github.com/gareth8118/geda-gaf.git
  $ git fetch gareth8118
  $ git remote add bert https://github.com/bert/geda-gaf.git
  $ git fetch bert
  $ gitk --all

Теперь gitk будет забит до отказа, но с помощью Файл → Список ссылок [File → List references] (F2) можно открыть диалоговое окно для более лёгкой навигации.

Обновление любимых веток сократится тогда до: 

  $ git fetch --all

... сделать заплату, чтобы отправить её разработчикам?

Самый простой способ, в котором в заплату включаются все изменения с тех пор, как локальный репозиторий синхронизировался с репозиторием на geda-project.org: 

$ git diff > имя_файла_заплаты

Более сложный способ с большим контролем над содержимым заплаты: 

$ git add -i           # выбрать файлы для внесения изменений
$ git status           # проверить, что будут внесены именно те изменения,
                       # которые вы намеревались внести
$ git commit           # внести изменения
$ git format-patch -1  # сделать файл заплаты, основанный на данных изменениях

Последняя команда выведет имя файла, содержащего заплату. Обязательно посмотрите документацию по git-format-patch, чтобы получить больше информации по этой команде. Полученный файл может быть отправлен по электронной почте разработчикам, имеющим доступ на запись, и наложен ими с помощью git apply.

... восстановить на самом деле испорченный локальный репозиторий?

Прежде всего не “продвигайте” с помощью push никакой репозиторий, если вы думаете, что он как-то испорчен. Спросите сначала кого-нибудь более опытного в git.

Во-вторых, команда, которая в самом деле спасёт вашу шкуру — это git-reflog. Она используется примерно так: 

 $ git reflog
 086908e... HEAD@{0}: cherry-pick: Last minute updates to the READMEs for all pro
 2a79a23... HEAD@{1}: checkout: moving to master
 2a79a23... HEAD@{2}: checkout: moving to master
 ...
 $ git reset --hard HEAD@{1}

Последняя команда (git reset --hard ...) откатит все ваши изменения к шагу “checkout: moving to master”. Помните: не паникуйте! С помощью git многое можно починить.