=for bif-doc #intro bif-doc-intro - a quick hands-on introduction

=head1 Introduction To Bif

L<Bif|bif> is a command-line project management tool. This is an
introduction to version 0.1.5_1 (2015-06-30) based on situations
typically encountered by software developers. It is assumed that you
are comfortable working with command line programs and your operating
system shell (e.g. bash).

=begin comment

    =head1 Initialize your identity

    Some bif actions require your name and email address. Run the following
    command before doing anything else to set them up:

=for bifcode #!sh

        bif new id my@email.address My Name

=end comment

=head1 Creating your user identity

Bif needs to know who you are when you make changes. You create your
identity in a special user repository (typically F<$HOME/.bifu>) when
you pass the C<--user-repo> option to the L<bif-init> command:

=for bifcode #!sh

    $ bif init --user-repo

You only need to do this once.

=head1 Initialize a repository

A repository must be initialized before you can create any topics:

=for bifcode #!sh

    bif init

The very first time that L<bif-init> runs it also prompt the user for
various identity details and creates the user repository F<.bifu>,
before continuing with the original action.

=head1 Create, List And Modify Topics

Create a project, identified by a name and a title. You will also be
prompted to add an initial change message.

=for bifcode #!sh

    bif new project todo Things to do

Create some tasks and issues. Use the C<--message|-m> option to prevent
your $EDITOR from being invoked.

=for bifcode #!sh

    bif new task Take out the rubbish
    bif new issue I need more spare time -m "meh!"

Retrieve the lists of things you have created:

=for bifcode #!sh

    bif list projects
    bif list topics

Change the status of some things using the C<change> command, but first
you might want to know which status types are valid:

=for bifcode #!sh

    bif list task-status
    bif update 16 closed

View the history of changes to a particular topic:

=for bifcode #!sh

    bif log 16

Not giving an ID argument to C<log> will display the entire history of
the repository.

=head1 Share An Issue Between Two Projects

=for bifcode #!sh

    bif new project other Someone elses problem
    bif push 17 other

But recognise that their status can be individually modified:

=for bifcode #!sh

    bif update 45 closed

So how do we see all the current statuses of an issue?

    bif show 45

=head1 Fork An Existing Project

Say you are managing a software project, and you are releasing a new
version but are also continuing to work on your development branch.
Rather than having to push each issue separately from the old project
to the new we can just fork the old one.

=for bifcode #!sh

    bif new project v2 --fork devel

And notice that the new project has exactly the same issues as the
original:

=for bifcode #!sh

    bif list topics

=head1 Collaborating With Others

Need to import the project details from an organisation's hub
somewhere.

=for bifcode #!sh

    bif pull hub organisation@hub.com

Then, most likely, someone else already created the project, and you
just want to work on it too:

=for bifcode #!sh

    bif import todo organisation
    bif list projects

Then to exchange changes you make and get changes others have made,
just call C<sync>:

=for bifcode #!sh

    bif sync

=head1 See Also

L<bif-doc>

=head1 Author

Mark Lawrence E<lt>nomad@null.netE<gt>

=head1 Copyright and License

Copyright 2013-2015 Mark Lawrence <nomad@null.net>

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 3 of the License, or (at your
option) any later version.

