Contents

Intro

ABF Console Client aims to simplify remote work with ABF using command line and supports most active stages of a project life cycle - modification, building and publishing.

In ROSA, OpenMandriva and derived systems ABF console client is included in the abf-console-client package and laucnhed by typing abf command.

First launch and configuration

When launched for the first time, ABF console client will ass you for necessary parameters (user name, password, etc.) and some default option (e.g., default group, build platform, etc.). All these settings will be saved to .abfcfg file in your home directory. To change your settings, edit this file or remove it and launch abf command. Note that this file also stores alias definitions which will be lost if you remove the file.


Getting Started

Typical actions with ABF console client can be performed in the following way:

abf get PROJECT

where PROJECT is a project name with owner (owner/proj_name). Owner can be omitted, default group will be used. This command is equivalent of "git clone" invoked with URL to corresponding Git repository.

abf put -m MSG

This command first scans the directory for binary files (e.g., tarballs with source code), upload them to ABF File Store and put their hash sums into .abf.yml file. Then it parses spec file and tries to detect Sources which are present in .abf.yml but are no longer used. If these sources are binary files mentioned in .abf.yml, then they are moved to the "removed sources" section of that file so they will not be fetched from File Store when package is being built. Then "abf put" invokes the "git add --all; git commit -m MSG; "git push" sequence of commands.

abf build

When called without arguments, this command takes a look at active Git branch, asks ABF about repositories this branch is associated with and initiates a build from the branch to that repositories. You can specify branch to be used and target repositories as additional parameters.

abf status ID

This command will provide you with a short information about a particular build task. ID of the task is printed to STDOUT by "abf build". You can omit this parameter; in this case status of the last launched project will be checked.

abf publish ID

If you package has been successfully built, you can publish it to repository. Alternatively, you can specify "--auto-publish" option when invoking "abf build". Note that the latter option will work only if automated publishing is allowed by repository settings and if there is no package with the same name, version and released already published to the target repository.

Example

Let's clone import/gcc project, modify something inside it (source tarballs and/or spec) and rebuild the package.

 abf get import/gcc -b rosa2012.1
 cd gcc
abf put -m "My brand new gcc version"
 
abf build

(this command prints IDs of initiated build tasks. These IDs are also saved in ~/.abf_projects)

abf status
abf status <ID1> <ID2> ...
 
abf publish <ID1> <ID2> ...

Command Reference

Below is the list of all commands officially supported in ABF console client. You can also invoke abf --help and use abf help' command to get descriptions of the commands and actions supported by your version of the client.

help

If you want to get a help for some command, you can launch either abf help <command> or abf <command> -h/--help


Invocation and Options:

abf help <command_name>

add

Add project to repository.

You can't build project to repository unless you explicitly add the project to repository.

Invocation and Options:

abf add [-h] [-p PROJECT] [-v] repository

alias

Manage aliases for console client. With aliases you can make your frequently used commands shorter.

For example, you are going to work only with packages for rosa2012.1, you have to checkout to this branch after every "abf get" (or use -b rosa2012.1). But you can just add an alias like "g: get -b rosa2012.1" and after that "abf g" will do it automatically.

Moreover, the alias name can be not only the first abf argument. For example, you can create another useful alias like "pack: rosa2012.1 build_branch -p" and run "abf copy pack" to copy contents of rosa2012.1 branch to build_branch and compress it.

Invocation and Options:

abf alias <action> param1 [param2] [...]

add

Add a new alias. the first argument is an alias name, all the arguments after that are alias target. For example, abf alias add sg search groups will срфтпу every call of "abf sg rosa" to "abf search groups rosa".

list

List all the currently available aliases. By default this list looks like

        b: build
       sp: search projects
       su: search users
       st: status
        s: store
      spl: search platforms
       sg: search groups

remove

Remove an alias. The only option is an alias name.

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.

Invocation and Options:

abf build [--project <project>] [--branch <branch>] [--tag <tag>] [--commit <commit>] [--save-to-repository <repository>] [--repository <repository>] [--arch <arch>] [--auto-publish] [--update-type <type>] [--skip-spec-check]

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:

Other options resolving:

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).

Examples:

chain_build

Initiate a chain of build tasks on ABF. Accepts almost the same set of options as abf build. Note that unlike abf build, chain_build doesn't automatically detect values for different options. You have to manually specify all options necessary for the build - in particular, "save-to" repository and repositories to build with (see example).

Invocation and Options:

abf chain_build [-h] [-i INFILE] [-b BRANCH] [-t TAG] [-c COMMIT] [-u TIMEOUT] [-s SAVE_TO_REPOSITORY] [-a ARCH] [-r REPOSITORY] [-l BUILD_LIST] [--auto-publish] [--auto-publish-status {default,none,testing}] [--skip-personal] [--testing] [--no-extra-tests] [--auto-create-container] [--cached-chroot] [--save-chroot] [--update-type {security,bugfix,enhancement,recommended,newpackage}] [-v] [project [project ...]]

Extra arguments and options with respect to abf build:

Example:

abf chain_build urpmi apache:dracut texinfo -b rosa2014.1 -s abf_personal/main -r rosa2014.1/main -r rosa2014.1/contrib --auto-publish-status=none --auto-create-container

Build of every successive chain will be initiated only if all builds from the previous chain were completed successfully and only after containers for all of them are created. These containers will be automatically attached to builds of all successive chains.

clean

Scan the spec and .abf.yml files for possible problems. First, it detects missing sources or patches (which are mentioned in spec using non-remote path, but are absent in current directory and .abf.yml). The check will also fail if there are some problems with the spec file itself and RPM can't parse it. These checks are automatically executed when creating a build task from the current directory. If they fail, the console client refuses to create a build task. This behavior can be turned off by --skip-spec-check option for the build command.

In addition, the 'clean' check reports warnings about files specified in .abf.yml and at the same time in the spec file with remote URL. These warnings are not considered to be crucial and don't prevent the build from being started

Invocation and Options:

abf clean [--auto-remove]

copy

Copy files from one git branch to another. Be careful: all the files from destination branch will be removed, and replaced by the files from a source branch.

This command can be useful to keep sources of the project in one branch and build package in another.

Invocation and Options:

abf copy [-h] [-p] [-v] src_branch [dst_branch]

create

Create a project from SRPM file.

Invocation and Options:

abf create [-h] [-b BRANCH] [--no-def-branch] [-v] srpm [owner]

destroy

Destroy project. Be careful - destroyed project can't be restored!

Invocation and Options:

abf destroy [-h] [-v] project

fetch

Download all the files listed in .abf.yml from File-Store to local directory.

Invocation and Options:

abf fetch [--only <file_name>]

fork

Fork project.

Invocation and Options:

abf fork [-h] [-v] source_project [target_project]

get

Clone a remote git repository by its group and name. For example, abf get import/gcc will clone a project gcc from group import.

Invocation and Options:

abf get <project> [--branch <branch_name>]

Notes:

You can omit a group name, your default group (given from configs) will be used.

info

Get information about single instance - platform, repository or project.

Invocation and Options:

abf info {platforms,repositories,projects} [-f [FILTER [FILTER ...]]] [-o [OUTPUT [OUTPUT ...]]]

Example

locate

Command to maintain a database of local projects.

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 <project>.

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.

Invocation and Options:

abf locate [<action>] [--project <project>] [--directory <directory>]

mock-urpm

Build a project locally using mock-urpm. No checkouts will be made, the current git repository state will be used.

Invocation and Options:

abf mock-urpm [-c <config>]

Notes:

proj_alias

Create alias of existing projects. Aliases act like different ABF projects but share the same Git repository.

Invocation and Options:

abf proj_alias [-h] [-v] source_project target_project

publish

Publish the task that have already been built.

Invocation and Options:

abf publish <task_id> [<task_id>] [...]

pullrequest

Send a pull request from SRC_BRANCH to DST_BRANCH

Invocation and Options:

abf pullrequest [-h] [-p PROJECT] [-v] from_ref to_ref title body

Positional arguments:

Optional arguments:

put

Upload binary files to File-Store and update (or create) .abf.yml file. Can also commit and push changes.

Invocation and Options:

abf put [-m|--message <message>] [--minimal-file-size <size>] [--do-not-remove-files]

remote

Add remote Git repository and fetch its contents.

Invocation and Options:

abf remote [-h] [-v] remote_group [remote_name]

Example:

 abf get openmandriva/foo
 abf remote import
 git merge import/rosa2014.1

remove

Remove project from repository.

Once you removed project from repository, you will not be able to build it for that repository anymore.

Invocation and Options:

abf remove [-h] [-p PROJECT] [-v] repository

rpmbuild

Build a project locally using rpmbuild. No checkouts will be made, the current git repository state will be used.

Invocation and Options:

abf rpmbuild [-h] [-b {b,s,a}] [-v]

Notes: No checkouts will be made,the current git repository state will be used

search

Search for something on ABF.

Invocation and Options:

abf search <target> "<query>"

show

Show some general information about the project. Bash autocomplete uses it. If you are in a git repository directory, command will show information about this project (unless -p/--project specified).

Invocation and Options:

abf show <target> [--project <project_name>]

Notes:

Repository name includes its platform name. Example of repository name: "rosa2012.1/main" - repository "main" of "rosa2012.1" platform.

Build repository - repository that you can connect to a building chroot.

Target (or save-to) repository - when a build task completed successfully, packages can be published to this repository.

status

Show information about a build list. 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

Invocation and Options:

abf status [--project <project>] [--short]

store

Upload a given file to File-Store. Prints a sha1 hash or error message (with non-zero return code).

If the file with same hash already presents on File-Store, it will not be reuploaded. In any case, file hash will be printed.

Invocation and Options:

abf store <path>

test

Execute a set of internal datamodel tests.

update

Change project settings.

Invocation and Options:

abf update [-h] [-p PROJECT] [--name [NAME]] [--desc [DESC]] [--visibility {open,hidden}] [--is_pkg {true,false}] [--branch [BRANCH]] [--issues {true,false}] [--wiki {true,false}] [--biarch {true,false}] [-v]

Additional features

Cache of local project locations

ABF client remembers locations of all repositories ever cloned using it and you can easily move to particular project directory in your local filesystem using "abfcd" command:

abfcd import/abf-console-client

This information is stored in .abf_projects file in your home directory.

You can learn the location of any project in your filesystem by executing

abf locate -p PROJECT

If you already have a set of repositories not known to the console client (e,g,m they were cloned using git directly or you removed your .abf_projects file), you can ask the console client to scan particular folders and add all project it finds there to its local cache:

abf locate update-recursive -d PATH

where PATH is a directory with repositories.

Information from .abf_projects file is also used by the console client to move files among different projects.

Cache update requires some time, so if you operate with a large set of projects, it can make sense to disable it by specifying --skip-proj-cfg-update option (supported for get, build and chain_build commands).

Bash autocompletion

ABF console client support rich autocompletion in Bash. In particular, it can suggest completions for option names, git branches, build- and save-to repositories for "abf build" and a lot of other parameters. As a result, it's much easier to work with console client, because you don't have to type the long repository name or remember the list of possible variants. In some cases autocompletion may take about 1 second, but remember that its results are always cached, so the next time it will be much more faster.