ABOUT

-----

This is bash completion support for osc (openSUSE build service

command-line tool).

DOWNLOAD

--------

The project is hosted on gitorious.org. To get the latest version,

use the following command:

git clone git://gitorious.org/opensuse/osc-bash-completion.git

INSTALLATION

------------

A)

If you have bash-completion package installed and enabled, you can

copy the osc.sh file into /etc/bash_completion.d directory. Then open

new terminal (so that the completion script) gets loaded and osc

completion should work.

B)

If you don't have bash-completion installed or you don't want to put

the completion script in /etc for whatever reason, you can use the

completion script as follows:

1) copy the osc.sh file somewhere (e.g. ~/.osc-completion.sh)

2) add the following line to your .bashrc:

   source ~/.osc-completion.sh

For the time being, the script does not check osc is installed and

properly set up (list password/username stored in ~/.oscrc). So please

make sure that osc is installed and working (e.g. by running 'osc ls

openSUSE:Factory') before trying the completion.

You might also want to look at how you can customize the completion:

see CUSTOMIZATION section.

REQUIREMENTS

------------

Working osc installation is needed. Tested with osc-0.130git. It

should more or less work with other osc versions as well. I plan to

make future versions less dependent on osc-version.

The script works with bash-4.x. I have no idea if it might work/works

with other shells too (but I doubt so). If the changes to make it

compatible with other shells were not too intrusive, I'll be happy

to accept patches ;)

FEATURES

--------

The script provides support for completing:

 * osc subcommand names (checkout, commit, ...)

 * global long osc options (e.g. --quiet, --debug, ...)

 * long subcommand options

 * project names

 * package names (in given project)

 * file names (in given project/package)

 * repository names (openSUSE_Factory, ...)

 * architectures (i586, x86_64, ...)

 * ...

Examples:

 * osc com<tab><tab> => osc commit

 * osc --ht<tab><tab> => osc --http-debug

 * osc build --a<tab><tab> => osc build --alternative-project

 * osc ls Ar<tab><tab> => osc ls Archiving

 * osc ls Base:System pa<tab><tab> =>  osc ls Base:System parted

 * osc cat Base:System parted ba<tab><tab> => osc cat Base:System parted baselibs.conf

 * osc buildlog openSUSE_<tab><tab> => osc buildlog openSUSE_

   openSUSE_Factory  openSUSE_11.0     openSUSE_11.1     openSUSE_11.2

   - works in package working directory

 * osc buildlog openSUSE_Factory x<tab><tab> => osc buildlog openSUSE_Factory x86_64

       - works in package working directory

 * osc createrequest -a <tab><tab> => osc createrequest -a

   add_role delete change_devel set_bugowner submit

 * osc ? d<tab><tab> => osc ?

   delete deleterequest dependson diff

 * osc meta a<tab><tab> => osc meta attribute

 * osc my <tab><tab> => osc my

   pkg prj rq sr

 * osc request <tab><tab> => osc request

   accept approvenew co     decline checkout

   list   log        revoke show    wipe

 * osc getpac for<tab><tab> => osc getpac fortune

At the moment, the script DOES NOT provide support for completing:

- short options

- arguments for most of the options

- some complex combinations of arguments (see TODOs in osc.sh)

Also, the script does not work correctly if there is a long option

with argument and there is '=' between the option and argument

(--long-option=arg). Please use the '--long-option arg' form instead.

Fixing this is in TODO list.

For the time being, the script does not recognize alternative apiurl

(-A|--apiurl) and thus it works only with default

(https://api.opensuse.org) api. This is in TODO list as well.

To avoid long delays and spamming OBS server too much, the script

caches several information:

- list of projects in

  ~/.osc_bash_completion/default/prjlist

- list of packages in project in

  ~/.osc_bash_completion/default/${prj}_pkglist

- list of enabled repositories/architectures

  (output of 'osc repos prj') in

  ~/.osc_bash_completion/default/${prj}_repos

The list of projects (prjlist) is generated when needed. It takes several

seconds to generate the list, so you'll notice significant delay on

the first completion.

By default, the prjlist contains all projects in the build service.

As of this writing, there are more than 13k projects, which make

the completion somewhat slow - see CUSTOMIZATION for information how

to avoid this.

The ${prj}_pkglist and ${prj}_repos are generated when needed, only

for the given project. For instance, the "osc cat Base:System <tab><tab>"

will generate Base:System_pkglist file. Next time, no communication

with the OBS server will be necessary. See CUSTOMIZATION for info

about keeping the cache up-to-date.

Note: when completing particular filename in a package (e.g.

"osc cat Base:System parted part<tab><tab>"), the list of files

in Base:System/parted is not cached anywhere, but is

generated on the fly.

If no completion is found, it defaults to filename completion.

CUSTOMIZATION

-------------

Updating prjlist

~~~~~~~~~~~~~~~~

The completion script provides a mechanism to restrict caching of

projects list to some subset of all projects, which makes completion

significantly faster and also gives you less options if the completion

is ambiguous.

By default, it caches list of all projects. This behavior can be

changed by providing custom script that generates list of projects

that you are interested in. If the completion script finds

user-provided script named

~/.osc_bash_completion/default/prjlist_update.sh, it takes it's output

and stores it as prjlist (the script must be executable).

Having prjlist contain all projects except home:* projects, but

including my home projects (home:myusername*) seems to work

sufficiently fast, while still including most of the projects

I might want to work with. However, any other subset of projects in

prjlist should work as well.

You can use the provided prjlist_update.sh as a template for the

script (don't forget to put your OBS username there).

The drawback of not having all OBS projects in prjlist is that it

breaks completion if one of the projects not listed in prjlist appears

on the commandline (it is not detected as being a project name and the

completion logic breaks).

The completion script does never update the prjlist [*]. For this

reason, it might be appropriate to update the prjlist regularly as a

cronjob. To make prjlist update once a day, put following line to your

crontab:

30 3 * * * ~/.osc_bash_completion/default/prjlist_update.sh > ~/.osc_bash_completion/default/prjlist

Please use some random time, so that we don't overload OBS if this

becomes too popular :)

[*] However, this will probably change in the future, so that

the completion script will update the prjlist on its own if

it detects that the prjlist is too old.

Updating *_{pkglist,repos}

~~~~~~~~~~~~~~~~~~~~~~~~~~

Similarly, the ${prj}_pkglist and ${prj}_repos files are

never updated by the osc completion script after they are created.

You can use provided update_prjs_cache.sh, which is a simple script

that updates all ~/.osc_bash_completion/default*_{prjlist,repos}

files. Suitable for running as a cronjob:

31 3 * * * /path/to/update_prjs_cache.sh

Only one <tab> for completion

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, the bash/readline requires you to hit <tab> key twice

before completing the word. If you prefer to hit it only once, put the

following into your ~/.inputrc:

set show-all-if-ambiguous on

See readline(3) for more details.

KNOWN PROBLEMS, TODO

--------------------

See TODO file

CONTRIBUTING

------------

Send all patches, suggestions, bug reports and constructive criticism

to the current maintainer: Petr Uzel <petr.uzel@suse.cz>

You can also try to contact the author on IRC: ptr_uzl @ freenode.net

Please send the patches in the "git format-patch ..." form if

possible. Nice HOWTO is here:

http://git.savannah.gnu.org/cgit/coreutils.git/plain/HACKING

--

Petr Uzel <petr.uzel@suse.cz>

ptr_uzl @ freenode.net