Консольный клиент ABF — различия между версиями
D uragan (обсуждение | вклад) (→copy: translate) |
D uragan (обсуждение | вклад) (→pullrequest: translate) |
||
| Строка 272: | Строка 272: | ||
==pullrequest== | ==pullrequest== | ||
| − | + | Отправить запрос на перенос изменений ("pull request") из ветки или метки SRC_BRANCH git-репозитория проекта в ветку DST_BRANCH этого же проекта. | |
'''Запуск и опции:''' | '''Запуск и опции:''' | ||
''abf pullrequest [-h] [-p PROJECT] [-v] from_ref to_ref title body | ''abf pullrequest [-h] [-p PROJECT] [-v] from_ref to_ref title body | ||
| − | + | * '''<from_ref>''': ветка-источник | |
| − | + | * '''<to_ref>''': целевая ветка | |
| − | * '''<from_ref>''': | + | * '''<title>''': название запроса |
| − | * '''<to_ref>''': | + | * '''<body>''': комментарий к запросу |
| − | * '''<title>''': | + | * '''-p <имя_проекта>, --project <имя_проекта>''': имя проекта в формате "владелец/название" (например, "import/gcc"). По умолчанию используется проект, в директории которого выполняется команда |
| − | * '''<body>''': | + | |
| − | + | ||
| − | + | ||
| − | * '''-p | + | |
| − | + | ||
==status== | ==status== | ||
Версия 15:20, 20 февраля 2014
Введение
Консольный клиент ABF предназначен для поддержки работы с ABF из командной строки и поддерживает наиболее часто выполняемые действия с проектами на - модификацию, сборку и публикацию.
Getting Started
Типичные действия с проектами посредством консольного клиента выполняются следующим образом:
- Клонирование репозитория проекта
abf get <имя_проекта>
Имя проекта может включать его владельца (в формате <владелец>/<имя_проекта> - например, import/gcc). Если владельца не указывать, то используется значение по умолчанию из настроек клиента.
Эта команда эквивалентна вызову "git clone" со ссылкой на репозиторий проекта.
- Применить все изменения, сделанные локально в git-репозитории, и отправить их в git-репозиторий на ABF
abf put -m <сообщение>
Эта команда сначала ищет в текущей директории бинарные файлы (например, архивы с исходным кодом), которые упомянуты в spec-файле, и помещает их в файловое хранилище ABF, прописывая соответствующий файлу идентификатор в файл .abf.yml. Затем клиент определяет, какие из файлов, уже присутсвующие в .abf.yml, больше не используются в spec-файле проекта и не нужны при сборке. Такие файлы перемещаются в секцию "removed sources" файла .abf.yml; они не будут загружаться из файлового хранилища при сборке на ABF. После этих дейтсивй, "abf put" запускает последовательность команд "git add --all; git commit -m MSG; "git push".
- Запустить сборку
abf build
при запуске без аргументов, эта команда смотрит на текущую ветку Git-репозитория, запрашивает у сервера ABF информацию о привязке этой ветки к репозиториям дистрибутивов и запускает сборку проекта с использованием текущей ветки для целевого репозитория дистрибутива. Ветку Git и целевой репозиторий дистрибутива можно указать с помощью дополнительных параметров.
- Узнать статус сборки
abf status ID
Эта команда выводит информацию о состоянии сборочного задания с заданным идентификатором. Если идентификатор опущен, будет напечатан статус последней запущенной вами сборки.
- Опубликовать результаты сборки в репозиторий
abf publish ID
Если сборка завершилась успешно, то с помощью этой команды можно опубликовать собранные пакеты в целевой репозиторий дистрибутива. Заметьте, что можно попросить ABF автоматически публиковать пакет в случае успеха, указав при вызове "abf build" опцию "--auto-publish". Однако для этого автоматическая публикация должна быть разрешена настройками репозитория, а также в целевом репозитории дистрибутива не должно содержаться пакета с таким же именем, версией и релизом, как собранный.
Пример
Давайте склонируем проект import/gcc project модифицируем его (например, положим новый архив с исходным кодом и обновим spec-файл) и пересоберем пакет.
- Cклонировать репозиторий проекта и перейти в его папку
abf get import/gcc -b rosa2012.1 cd gcc
- <производим действия по модификации пакета - кладем новый архив с исходным кодом, модифицируем spec-файл и так далее>
- Загрузить новый архив с исходным кодом в файловое хранилище ABF, прописать ссылку на него в файл .abf.yml и отправить все изменения в git-репозиторий на ABF
abf put -m "Обновленная версия gcc"
- Запустить сборку обновленного проекта на ABF
abf build
(заметьте, что эта команда печатает идентификаторы запущенных задач - они могут вам пригодиться позже, для запроса статуса сборок. Эти идентификаторы также записываются в файл ~/.abf_projects)
- Узнать статус сборки
- эта команда выведет статус последней запущенной вами сборки:
abf status
- а также можно узнать статус сборочных заданий с заданными идентификаторами:
abf status <ID1> <ID2> ...
- Если сборка завершилась успешно, то можно опубликовать ее в репозиторий:
abf publish <ID1> <ID2> ...
Описание команд
Ниже дан список команд, официально поддерживаемых последней версией консольного клиента ABF. Вы можете запустить abf --help или abf help' для получения описаний команд, поддерживаемых вашей вресией клиента.
help
Получение детальной справки по конкретной команде (обратите внимание, что наряду с abf help <имя_команды> вы можете использовать abf <имя_команды> -h/--help)
Запуск и опции:
abf help <имя_команды>
- <имя_команды>: Имя команды, для которой необходимо вывести справку.
alias
Управление псевдонимами консольного клиента. Псевдонимы используются для краткой записи часто используемых команд, сокращая время на их вызов.
Например, если вы в большинстве ваших проектов работаете в git-веткой rosa2012.1, то вам приходится ихз клонировать командой "abf get -b rosa2012.1" (или выполнять сначала "abf get", а потом переходить в директори склонированного проекта и выполнять там "git checkout rosa2012.1").
Однако вместо этого, вы можете определить псевдоним на сочетание опций "get -b rosa2012.1". Например, назвав этот псевдоним одной буквой "g", вы сможете просто запускать команду "abf g" и получать тот же эффект, что и при запуске "abf get -b rosa2012.1".
Заметьте, что псевдоним может замещать только часть опций и использоваться в любом месте в строке вызова. Например, можно назначить псевдоним "pack" для сочетания "rosa2012.1 build_branch -p" и запускать "abf copy pack" для копирования содержимого ветки rosa2012.1 в ветку build_branch со сжатием.
Запуск и опции:
abf alias <action> param1 [param2] [...]
- <action>: Одно из действий: list, add, remove.
list
Вывести перечень доступных псевдонимов. По умолчанию доступны следующие псевдонимы:
b: build
sp: search projects
su: search users
st: status
s: store
spl: search platforms
sg: search groups
add
Добавить псевдоним. Необходимо указать как минимум два аргумента - первый является именем псевдонима, а все остальные образуют его тело. Например, abf alias add sg search groups добавит псевдоним sg, который при вызове клиента будет заменяться на "search groups".
remove
Удалить псевдоним. В качестве аргумента необходимо передать имя псевдонима, например abf alias remove sg.
clean
провести анализ spec-файла и файла .abf.yml на пердмет ошибок. в первую очередь, команда "abf clean" проверяет доступность всех файлов с исходным кодом и патчей, перечисленных в spec-файле - эти файла должны либо присутсвовать в локальной директории, либо быть указаны в основной секции .abf.yml, либо для них должны быть указаны ссылки в сети Интернет. Также осуществляется проверка корректности spec-файла - если его не удается обработать средствами RPM, то выводится соответствующая ошибка.
Отметим, что эти проверки (доступность исходных файлов и корректность spec-файлов) производятся автоматически перед запуском каджой сборки посредством "abf build". Если эти проверки находят ошибки, то консольный клиент откажется запускать сборку проекта (это поведение может быть переопределено опцией "--skip-spec-check").
В дополнение косновным проверкам, "abf clean" выводит предупреждения о файлах, которые одновременно прописаны в .abf.yml и для которых указаны Интернет-адреса в spec-файле.
get
Склонировать удаленный git-репозиторий по его владельцу и имени на локальную машину. Например, abf get import/gcc склонирует проект gcc из группы import. Проект будет склонирован в текущую директорию. Если в директории уже есть поддиректория, чье имя совпадает с именем проекта, консольный клиент откажется выполнять клонирование и выдаст соответсвующее предупреждение.
Запуск и опции:
abf get <имя_проекта> [--branch <имя_ветки>]
- <имя_проекта>: имя проекта для клонирования в формате <владелец>/<название> (например, import/gcc). Если имя владельца не указывать, то используется значение по умолчанию из настроек консольного клиента.
- -b/--branch <имя_ветки>: имя ветки git-репозитория, которая будет автоматически сделана активной после клонирования (то есть после клонирования abf дополнительно вызовет команду "git checkout <имя_ветки> внутри директории проекта").
put
Загрузить изменения в проекте, сделанные локально, на сервер ABF.
Первым шагом комагда "abf put" загружает бинарные файлы из текущей директории на файловый сервер ABF и добавляет их идентификаторы в файл .abf.yml. После этого определяются файлы, указанные в .abf.yml, которые больше не нужны для сборки (не упоминаются в spec-файле проекта). Такие файлы перемещаются в секцию removed_sources файла .abf.yml; они не будут извлекаться при сборке проекта на ABF. после этого все изменения в проекте, сделанные локально применяются и отправляются в удаленный git-репозиторий (аналогично командам "git add --all", "git commit" и "git push"). По умолчанию бинарные файлы, загруженные на файловый сервер ABF, из текущей директории удаляются.
Запуск и опции:
abf put [--message <сообщение>] [--minimal-file-size <size>] [--do-not-remove-files]
- -m/--message <сообщение>: комментарий к изменениям (передается команде "git commit")
- -s/--minimal-file-size <size>: минимальный размер бинарного файла, при превышении которого файл загружается на файловый сервер. По умолчанию используется 0, то есть на файловый сервер загружаются все бинарные файлы.
- -n/--do-not-remove-files: Не удалять бинарные файлы из текущей директории после их загрузки на файловый сервер ABF.
Замечание: Консольный клиент использует легковесный анализатор spec-файлов и не всегда может корректно определить, нужен тот или иной бинарный файл для сборки или нет. В случае неопределенности считается, что файл нужен, и он остается в основной секции файла .abf.yml. Поэтому имеет смысл периодически просматривать .abf.yml и производить их ручную чистку от ненужных файлов - это позволит ускорить сборку проектов за счет снижения расходов на исвлечение ненужных файлов из файлового хранилища.
store
Загрузить заданный файл на файловое хранилище ABF. В случае успеха, клиент напечатает идентификатор файла (sha1-сумму).
Если файл с такой же хэш-суммой уже присутствует в файловом хранилище, но он не будет перезаписан.
Запуск и опции: abf store <path>
- <path>: Путь к файлу для загрузки.
fetch
Загрузить все файлы, указанные в основной секции файла .abf.yml, в текущую директорию. Файлы, указанные в секции "removed_sources", не загружаются.
Запуск и опции:
abf fetch [--only <file_name>]
- -o/--only <file_name>: Limit the list of downloaded files to this file name(s). This option can be specified more than once.
show
Показать детальные сведения о проекте. Эта команда используется для автодополнения в оболочке Bash.
Запуск и опции:
abf show <target> [--project <имя_проекта>]
- <target>: Какую именно информацию показывать. Доступные варианты:
- build-repos - репозитории, которые можно подключать при сборке проекта
- build-platforms - платформы, репозитории которых можно подключать при сборке проекта
- save-to-repos - репозитории, в которые можно публиковать результаты сборки проекта (пакеты)
- save-to-platforms - платформы, в репозитории которых можно публиковать результаты сборки проекта (пакеты)
- -p/--project <имя_проекта>: Имя проекта, о котором необходимо показать информацию. Если вы находитесь внутри git-репозитория проекта, то можно эту опцию не указывать, в этом случае будут выведены данные о текущем проекте.
Замечание: в имя репозитория всегда включается имя платформы, к которой он относится - например, "rosa2012.1/main" соответствует репозиторию "main" платформы "rosa2012.1".
locate
Управление локальным кэшем репозиториев.
Console client tends to maintain a database of local projects: while any interaction with your local git repository via abf-console-client, it stores the path to this repository. After that you can call abfcd [<project_group>/]<project_name> (omit group_name to use your default) to change your current working directory to the project's path (if it had been stored before). If you just want to get a project path without changing directory, use abf locate -p <имя_проекта>.
You can also add projects to this database by manually. To add only one project call abf locate update -d /path/to/project. To scan directory recursively and add all the found projects, call abf locale update-recursive -d /path/to/directory.
Запуск и опции:
abf locate [<action>] [--project <имя_проекта>] [--directory <directory>]
- <action>: одно из действий "update" или "update-recursive". update will update
- -p/--project <имя_проекта>: Project to show information for (if needed). Format: "[group/]name". If no group specified, your default group will be used.
- -d/--directory <directory>: Directory to update locations for. It should be a git repository for "update" and any directory for "update-recursive". If not specified - the current directory will be used.
build
Initiate a build task on ABF. There are lots of options, but in most cases it works great with no options at all. abf-console-client tries to automatically resolve all the options needed. How does it work: read notes and examples.
Запуск и опции:
abf build [--project <имя_проекта>] [--branch <branch>] [--tag <tag>] [--commit <commit>] [--save-to-repository <repository>] [--repository <repository>] [--arch <arch>] [--auto-publish] [--update-type <type>] [--skip-spec-check]
- -p/--project <имя_проекта>: project name ([group/]project). If the option is not specified and you are in a git repository directory - a project name will be resolved automatically.
- -b/--branch <branch>: git branch name to build. Read notes.
- -t/--tag <tag>: git tag to build. Read notes.
- -c/--commit <commit>: git commit sha hash to build. Read notes.
- -s/--save-to-repository <repository>: repository to save results to. If no platform part specified, it is assumed to be "<default_group>_personal". If this option is not specified at all and you are in a git repository, it will be resolved automatically (read notes).
- -r/--repository <repository>: repositories to build with. Can be set more than once. If no platform part specified, it is assumed to be your "<default_build_platform>". If no repositories were specified at all, it will be resolved automatically (read notes).
- -a/--arch <arch>: architectures to build for. Can be set more than once. If not set - use all the available architectures for the project given.
- --auto-publish: в случае успешной сборки, автоматически публиковать собранные пакеты в целевой репозиторий.
- --update-type <type>: Тип обновления. Допустимые значения: security, bugfix, enhancement, recommended, newpackage. По умолчанию используется "bugfix".
- --skip-spec-check: Не осуществлять проверки spec-файла и .abf.yml (см. описание команды clean).
Notes:
Console client tries to automatically resolve all the options without taking into account anything except --branch. If it fails - use only user-given options. If succeeds, but user specified other parameters - discard everything we've resolved and use only user-given options.
Git hash resolving:
- Only one of --branch, --tag or --commit options can be used at once.
- If you've specified commit hash - it will be used "as is".
- If you've specified branch or tag name - commit hash will be resolved automatically using ABF API. (the hash of top commit in the branch will be used for branch)
- If you've specified a project name - you have to specify a branch, tag or commit manually.
- If you've specified no branch, tag or commit hash and you've not specified a project name (you have to be in a git repository) - the top remote commit of your current branch will be used.
Other options resolving:
- if no --arch specified, use all the available project architectures.
- build repository can usually be resolved from a git branch name. If there is a build platform with the name of your current git branch exists - it will be used.
- save-to repository: if some repository from a build platform can be used as save-to repository - it will be used.
You can execute abf build (with no options) when you've specified a branch name (or it's resolved automatically) and there is a platform on ABF having the same name. In this case a save-to repository will be selected from a list of available save-to repositories for this platform. Build repositories are repositories of this platform too("main" and one another repository if needed for selected save-to repository).
Примеры:
- Build a current branch of a local cloned project. Build and save-to repositories can be resolved from branch name: abf build
- Build a project without a local git repository. Build and save-to repositories can be resolved from branch name: abf build --project import/gcc --branch rosa2012.1
- Build a project to another platform: abf build --project import/gcc --branch rosa2012.1 --save-to-repository rosa2012lts/contrib. Build repositories will be rosa2012lts/main and rosa2012lts/contrib.
mock-urpm
Собрать проект локально с использованием mock-urpm. Для сборки используется текущее состояние локального репозитория.
Запуск и опции:
abf mock-urpm [-c <config>]
- -c/--config <config>: A config template to use. Specify one of the config names from /etc/abf/mock-urpm/configs/. Directory path and extension (".cfg") should be omitted. If no config specified, "default.cfg" will be used. Autocompletion worsk for config names.
Замечание:
- Перед сборкой пакета вызывается "abf fetch". При этом если вы в текущей директории модифицировали какой-то файл, который прописан в .abf.yml, то ваш файл будет перезаписан версией из файлового хранилища.
- Сборка с помощью mock-urpm производится в директории /var/lib/abf/mock-urpm.
rpmbuild
Собрать проект локально с использованием rpmbuild. Для сборки используется текущее состояние локального репозитория.
Запуск и опции:
abf rpmbuild [-h] [-b {b,s,a}] [-v]
- -b {b,s,a}, --build {b,s,a} - собрать SRPM-пакет (s), бинарный RPM-пакет (b) или оба (a)
publish
Опубликовать успешно завершенное сборочное задание.
Запуск и опции:
abf publish <task_id> [<task_id>] [...]
- <task_id>: идентификатор сборочного задания
copy
Копировать файлы из одной ветки git-репозитория в другую. Будьте осторожны, существующие файлы в целевой ветке будут перезатерты!
Запуск и опции:
- <src_branch>: Исходная ветка, из которой копируются файлы
- <dst_branch>: Целевая ветка, в которую копируются файлы. Если этот аргумент пропущен, файлы копируются в текущую ветку
- -p/--pack: Создать архив в формате tar.gz из файлов исходной ветки и скопировать в целевую ветку этот архив, а не сами файлы
pullrequest
Отправить запрос на перенос изменений ("pull request") из ветки или метки SRC_BRANCH git-репозитория проекта в ветку DST_BRANCH этого же проекта.
Запуск и опции:
abf pullrequest [-h] [-p PROJECT] [-v] from_ref to_ref title body
- <from_ref>: ветка-источник
- <to_ref>: целевая ветка
- <title>: название запроса
- <body>: комментарий к запросу
- -p <имя_проекта>, --project <имя_проекта>: имя проекта в формате "владелец/название" (например, "import/gcc"). По умолчанию используется проект, в директории которого выполняется команда
status
Показать информацию о сборочном задании. It will print something like that:
Buildlist ID: 944492 User: akirilenko Project: import/mock-urpm Status: build has been published Build for platform: rosa2012.1 Save to repository: rosa2012.1/main Build repositories: [rosa2012.1/main] Architecture: i586 Created at: 2013-02-12 15:25:09 Updated at: 2013-02-12 15:43:16
Запуск и опции:
abf status [--project <имя_проекта>] [--short]
- -p/--project <имя_проекта>: Project. If last IDs for this project can be found in local database - use them. Otherwise, print error message end exit.
- -s, --short: Show only one-line information including id, project, arch and status.
clean
Analyze spec file and show missing and unnecessary files from the current git repository directory.
Запуск и опции:
abf clean [--auto-remove]
- -a/--auto-remove: автоматически удалять все ненужные файлы.
search
Поиск по ABF.
Запуск и опции:
abf search <target> "<query>"
- <target>: область поиска; допустимые значения:
- users - пользователи
- groups - группы
- platforms - платформы
- projects -проекты
- <query>: Строка для поиска. Регулярные выражения и шаблоны не поддерживаются.
test
Запустить набор внутренних тестов.
Эта команда может быть использована для проверки исправности консольного клиента и окружения. В штатном режиме работы, тесты не должны выявлять никаких проблем и должны печатать результирующую фразу "Datamodel seems to work fine".
Дополнительные возможности
Кэш локального местоположения проектов
Консольный клиент ABF запоминает метоположение в файловой системе всех репозиториев, склонированных с его помощью. За счет этого, вы можете быстро перемещаться между склонированными проектами с помощью команды "abfcd":
abfcd <имя_проекта>
Эта информация хранится в файле .abf_projects в вашей домашней директории.
Узнать местоположение проекта в вашей файловой системе можно с помощью следующей команды:
abf locate -p <имя_проекта>
Если у вас есть набор репозиториев, отсутствующих в кэше консольного клиента (например, если они были склонированы непосредственно с помощью команды git, или если вы удалили файл .abf_projects), вы можете заставить консольного клиента просканировать заданную директорию и поместить в кэш все проекты, которые он там найдет:
abf locate update-recursive -d <путь_к_директории_с_проектами>
Помимо команды "abfcd", информация из файла .abf_projects используется при перемещении файлов между различными проектами с помощью консольного клиента ABF.
Автодополнение в Bash
Консольный клиент ABF предоставляет богатые возможности по автоматическому дополнению команд и опций при использовании в оболочке Bash. В частности, он способен предлагать варианты дополнения для имен опций, веток git, целевых репозиториев для сборки (параметров build и save-to команды "abf build") и множества других команд. Это существенно облегчает работу с клиентом, поскольку отпадает необходимость в ручном вводе длинных имен и запоминании большого количества опций. В некоторых случаях автоматическое дополнение может работать более 1 секунды, однако все результаты обращения к автоматическому дополнению кэшируются и последующие вызовы проходят гораздо быстрее.
