NAME
    App::git::ship - Git command for shipping your project

VERSION
    0.16

DESCRIPTION
    App::git::ship is a git <http://git-scm.com/> command for building and
    shipping your project.

    The main focus is to automate away the boring steps, but at the same
    time not get in your (or any random contributor) way. Problems should be
    solved with sane defaults according to standard rules instead of
    enforcing more rules.

    This project can also "start" (create) a new project, just "build"
    (prepare for shipping) and "clean" projects.

    App::git::ship differ from other tools like dzil by not enforcing new
    ways to do things, but rather incorporate with the existing way. Example
    structure and how App::git::ship works on your files:

    *   my-app/cpanfile and my-app/Makefile.PL

        The cpanfile is used to build the "PREREQ_PM" and "BUILD_REQUIRES"
        structures in the ExtUtils::MakeMaker based "Makefile.PL" build
        file. The reason for this is that cpanfile is a more powerful format
        that can be used by Carton and other tools, so generating cpanfile
        from Makefile.PL would simply not be possible. Other data used to
        generate Makefile.PL are:

        "NAME", "LICENSE" will have values from "project_name" and
        "license". "AUTHOR" will have the name and email from the last git
        committer. "ABSTRACT_FROM" and "VERSION_FROM" are fetched from the
        main_module_path. "EXE_FILES" will be the files in "bin/" or
        "script/" which is executable. "META_MERGE" will use data from
        "bugtracker", "homepage" and"repository".

    *   my-app/CHANGELOG.md or my-app/Changes

        The Changes file will be updated with the correct timestamp, from
        when you ran the "build" action. The Changes file will also be the
        source for "next_version". Both "CHANGELOG.md" and "Changes" are
        valid sources.

    *   my-app/README

        Will be updated with the main module documentation using the command
        below:

          $ perldoc -tT $main_module_path > README;

        If you don't like this format, you can create "README.md" instead.
        The presense of that file will prevent "my-app/README" from getting
        generated.

    *   my-app/lib/My/App.pm

        This file will be updated with version number from the Changes file.

    *   .gitignore and MANIFEST.SKIP

        Unless these files exist, they will be generated from a template
        which skip the most common files. The default content of these files
        might change over time if new temp files are created by new editors
        or some other formats come along.

    *   t/00-basic.t

        Unless this file exists, it will be created with a test for checking
        that your modules can compile and that the POD is correct. The file
        can be customized afterwards and will not be overwritten.

SYNOPSIS
  Existing project
      # Set up .ship config and basic repo files
      $ cd my-project
      $ git ship start

      # make changes
      $ $EDITOR lib/My/Project.pm

      # build first if you want to investigate the changes
      $ git ship build

      # ship the project to git (and CPAN)
      $ git ship

  New project
      $ git ship -h
      $ git start My/Project.pm
      $ cd my-project

      # make changes
      $ $EDITOR lib/My/Project.pm

      # build first if you want to investigate the changes
      $ git ship build

      # ship the project to git (and CPAN)
      $ git ship

  Git aliases
      # git build
      $ git config --global alias.build = ship build

      # git cl
      $ git config --global alias.cl = ship clean

      # git start
      # git start My/Project.pm
      $ git config --global alias.start = ship start

  For developer
      package App::git::ship::some_language;
      use App::git::ship -base;

      # define attributes
      has some_attribute => sub {
        my $self = shift;
        return "default value";
      };

      # override the methods defined in App::git::ship
      sub build {
        my $self = shift;
      }

      1;

CONFIG
    "App::git::ship" automatically generates a config file when you "start"
    a new project.

    *   bugtracker

        URL to the bugtracker for this project.

    *   build_test_options

        This holds the arguments for the test program to use when building
        the project. The default is to not automatically run the tests.
        Example value:

          build_test_options = -l -j4

    *   class

        This class is used to build the object that runs all the actions on
        your project. This is autodetected by looking at the structure and
        files in your project. For now this value can be App::git::ship or
        App::git::ship::perl, but any customization is allowed.

    *   homepage

        URL to the home page for this project.

    *   license

        The name of the license to use. Defaults to "artistic_2".

    *   new_version_format

        This is optional, but specifies the version format in your "Changes"
        file. The example below will result in "## 0.42 (2014-01-28)".

          new_version_format = \#\# %v (%F)

        "%v" will be replaced by the version, while the format arguments are
        passed on to "strftime" in POSIX.

        The default is "%-7v %a %b %e %H:%M:%S %Y".

    *   project_name

        This name is extracted from either the "main_module_path" in
        App::git::ship::perl or defaults to "unknown" if no project name
        could be found. Example:

          project_name = My::App

    *   Comments

        Comments are made by adding the hash symbol (#) followed by text. If
        you want to use the "#" as a value, it need to be escaped using
        "\#". Examples:

          # This whole line is skipped
          parameter = 123 # The end of this line is skipped
          parameter = some \# value with hash

    *   Hooks

        It is possible to add hooks to the "CONFIG" file. These hooks are
        programs that runs in your shell. Example .ship file with hooks:

          before_build = bash script/new-release.sh
          after_build = rm -r lib/My/App/templates lib/My/App/public
          after_ship = cat Changes | mail -s "Changes for My::App" all@my-app.com

        Possible hook are "before_build", "after_build", "before_ship" and
        "after_ship".

ATTRIBUTES
  config
      $hash_ref = $self->config;

    Holds the configuration from end user. The config is by default read
    from ".ship.conf" in the root of your project.

  next_version
      $str = $self->next_version;

    Holds the next version to "ship".

  project_name
      $str = $self->project_name;

    Holds the name of the current project. This attribute can be read from
    "config".

  repository
      $str = $self->repository;

    Returns the URL to the first repository that point to "origin". This
    attribute can be read from "config".

  silent
      $bool = $self->silent;
      $self = $self->silent($bool);

    Set this to true if you want less logging. By default it silent is
    false.

METHODS
  abort
      $self->abort($str);
      $self->abort($format, @args);

    Will abort the application run with an error message.

  attr
      $class = $class->attr($name => sub { my $self = shift; return $default_value });

    or ...

      use App::git::ship -base;
      has $name => sub { my $self = shift; return $default_value };

    Used to create an attribute with a lazy builder.

  build
    This method builds the project. The default behavior is to "abort". Need
    to be overridden in the subclass.

  can_handle_project
      $bool = $class->can_handle_project($file);

    This method is called by "detect" in App::git::ship and should return
    boolean true if this module can handle the given git project.

    This is a class method which gets a file as input to detect or have to
    auto-detect from current working directory.

  detect
      $class = $self->detect;
      $class = $self->detect($file);

    Will detect the module which can be used to build the project. This can
    be read from the "class" key in "config" or will in worse case default
    to App::git::ship.

  run_hook
      $self->run_hook($name);

    Used to run a hook before or after an event. The hook is a command which
    needs to be defined in the config file. Example config line parameter:

      before_build = echo foo > bar.txt

  new
      $self = $class->new(%attributes);

    Creates a new instance of $class.

  render
      $self->render($file, \%args);

    Used to render a template by the name $file to a $file. The template
    need to be defined in the "DATA" section of the current class or one of
    the super classes.

  ship
    This method ships the project to some online repository. The default
    behavior is to make a new tag and push it to "origin".

  start
    This method is called when initializing the project. The default
    behavior is to populate "config" with default data:

    *   bugtracker

        URL to the bug tracker. Will be the the "repository" URL without
        ".git", but with "/issues" at the end instead.

    *   homepage

        URL to the project homepage. Will be the the "repository" URL,
        without ".git".

    *   license

        The name of the license. Default to artistic_2
        <http://www.opensource.org/licenses/artistic-license-2.0>.

        See "license" in CPAN::Meta::Spec for alternatives.

  system
      $self->system($program, @args);

    Same as perl's "system()", but provides error handling and logging.

  test_coverage
    This method check test coverage for the project. The default behavior is
    to "abort". Need to be overridden in the subclass.

  import
      use App::git::ship;
      use App::git::ship -base;

    Called when this class is used. It will automatically enable strict,
    warnings, utf8 and Perl 5.10 features.

    "-base" will also make sure the calling class inherit from
    App::git::ship and gets the has function.

SEE ALSO
    *   Dist::Zilla

        This project can probably get you to the moon.

    *   Minilla

        This looks really nice for shipping your project. It has the same
        idea as this distribution: Guess as much as possible.

    *   Shipit

        One magical tool for doing it all in one bang.

COPYRIGHT AND LICENSE
    Copyright (C) 2014, Jan Henning Thorsen

    This program is free software, you can redistribute it and/or modify it
    under the terms of the Artistic License version 2.0.

AUTHOR
    Jan Henning Thorsen - "jhthorsen@cpan.org"

