#!/usr/bin/perl

# ABSTRACT: Command-line utility for Pinto
# PODNAME: pinto

use strict;
use warnings;

#-----------------------------------------------------------------------------

our $VERSION = '0.007'; # VERSION

#-----------------------------------------------------------------------------

use App::Pinto;
exit App::Pinto->run();

#-----------------------------------------------------------------------------



=pod

=for :stopwords Jeffrey Ryan Thalhammer Imaginative Software Systems

=head1 NAME

pinto - Command-line utility for Pinto

=head1 VERSION

version 0.007

=head1 SYNOPSIS

First, create a configuration file at F<~/.pinto/config.ini>:

  # Required for all commands
  local = /some/directory

  # Optional, defaults to http://cpan.perl.org
  mirror = http://some-cpan-mirror

  # Required to add/remove your own archives
  author = MYNAME

Then, run some commands:

  # Create an empty repository
  $> pinto create

  # Add your own archive to the repository
  $> pinto add Foo-Bar-1.2.tar.gz

  # Fill your repository with latest packages from remote mirror
  $> pinto mirror

  # Then install stuff from your repository
  $> cpanm --mirror file:///some/directory --mirror-only Foo

=head1 DESCRIPTION

C<pinto> is a command line utility for managing a Pinto repository.
The repository can contain your own private archives of Perl packages,
and/or mirror archives from another repository (such as
L<http://cpan.perl.org>).  You can also put locally patched versions
of mirrored archives in your repository.

You can then point L<cpanm> to your Pinto repository and build and
install your private archives (and their dependencies).  B<NOTE:> At
this time, only L<cpanm> will work properly with a Pinto repository.
But support for L<cpan> and L<cpanp> is coming real soon!

=head1 CONFIGURATION

The following parameters can be set in your configuration file.  The
default location of this file is F<~/.pinto/config.ini>.  At the
moment, you cannot specify an alternative location for your
configuration file.

Almost all configuration parameters can also be specified on the
command line, either as global options or command options.  To display
a list of global options:

  $> pinto -help

To get a list of options for a particular command:

  $> pinto help <command>

=over 4

=item author = NAME

Your identity as a module author.  This could be your PAUSE ID, but it
doesn't have to be.  As long as it is just alphanumeric characters.
This parameter is required for C<add> and C<remove> commands.

=item local = DIR_PATH

The path to a directory where your repository will be kept.  This
parameter is required for all commands.  You must be able to read and
write to this directory.

=item nocleanup = (0|1)

If set to a true value, L<pinto> will not automatically clean up files
in your repository after most commands.  The default is 0.

=item mirror = URL

The URL of a repository that you would like to mirror.  This could
be a public CPAN mirror, or another Pinto repository.  Defaults
to L<http://cpan.perl.org>.

=item quiet = (0|1)

If true, then only fatal error messages will be displayed.  This
option silently overrides any C<verbose> setting.

=item store = CLASS_NAME

The name of the class that will handle storage of your repository.
The default is L<Pinto::Store>, which basically stores your repository
on the local file system.  Alternatives like L<Pinto::Store::Svn>
and L<Pinto::Store::Git> allow you to store your repository inside
a revision control system.  See the documentation for each of those
modules for additional configuration settings.

=item verbose = (0|1|2)

Controls how much noise is made.  Default is 0.

=back

=head1 COMMANDS

The following commands are available.  Say C<pinto help COMMAND>
to display a list of options available for C<COMMAND>.

=over 4

=item add Some-Archive-1.2.tar.gz

Adds the given archive to the Pinto repository.  Any packages
contained in those archives will override the mirrored packages with
the same name.  See the L<"RULES"> section for more information about
how locally added archives interact with mirrored ones.

=item clean

Deletes any archive in the repository that is not currently in
the master index.  This usually happens automatically, unless
you've set the C<nocleanup> option.

=item create

Creates a new, empty repository at the configured location.  You'll
get a warning if a repository already exists at that location.

=item list

Lists the curent packages and archives that are in the master index of
your repository.  This is basically just the contents of the
F<02packages.details.txt> file.

=item remove Some::Package

Removes the local archive that contains the given package.  All other
packages that were contained in the same archive are also removed.
After removing a package, you will usually want to run C<mirror> to
pull in any archives that might have been previously blocked by your
local ones.

=item mirror

Fills your repository with the archives that contain the latest
version of all packages on the remote mirror.  See the L<"RULES">
section for more information about how locally added archives interact
with mirrored ones.

=item verify

Reports any archives that are present in your repository but not
listed in the master index.  This is usually a sign that something
has gone wrong.

=back

=head1 RULES

There are certain rules that govern how the indexes are managed.
These rules are intended to ensure that clients pulling packages
from your repository will always get the B<right ones>.  Also,
the rules attempt to make Pinto behave somewhat like PAUSE does.

=over 4

=item A local package always masks a mirrored package, and all other
packages that are in the same archive with the mirrored package.

This rule is key, so pay attention.  If the remote mirror has an
archive that contains both C<Foo> and C<Bar> packages, and you add
your own archive that contains C<Foo> package, then both the C<Foo>
and C<Bar> mirroed packages will be removed from your index.  This
ensures that anyone pulling packages from your repository will always
get B<your> C<Foo>.  But they'll never be able to get C<Bar>.

=item You can never add an archive with the same name twice.

Most archive-building tools will put some kind of version number in
the name of the archive, so this is rarely a problem.

=item Only the original author of a local package can add a newer
version of it.

Ownership is given on a first-come basis, just like PAUSE.  So if
C<SALLY> is the first author to add local package C<Foo::Bar> to the
repository, then only C<SALLY> can ever add that package again.

=item Only the original author of a local package can remove it.

Just like when adding new versions of a local package, only the
original author can remove it.

=back

=head1 AUTHOR

Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Imaginative Software Systems.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut


__END__


