PkgTemplates.jl/README.md

# PkgTemplates

[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://invenia.github.io/PkgTemplates.jl/stable)
[![Latest](https://img.shields.io/badge/docs-latest-blue.svg)](https://invenia.github.io/PkgTemplates.jl/latest)
[![Build Status](https://travis-ci.org/invenia/PkgTemplates.jl.svg?branch=master)](https://travis-ci.org/invenia/PkgTemplates.jl)
[![Build Status](https://ci.appveyor.com/api/projects/status/r24xamruqlm88uti?svg=true)](https://ci.appveyor.com/project/christopher-dG/PkgTemplates-jl)
[![CodeCov](https://codecov.io/gh/invenia/PkgTemplates.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/invenia/PkgTemplates.jl)

**PkgTemplates is a Julia package for creating new Julia packages in an easy,
repeatable, and customizable way.**

## Installation

`PkgTemplates` is registered in
[`METADATA.jl`](https://github.com/JuliaLang/METADATA.jl), so run
`Pkg.add("PkgTemplates")` for the latest release, or
`Pkg.clone("PkgTemplates")` for the development version.

## Usage

The simplest template only requires your GitHub username.

```julia
julia> using PkgTemplates

julia> t = Template(; user="myusername");

julia> generate("MyPkg", t)
INFO: Initialized git repo at /tmp/tmpvaHVki/MyPkg
INFO: Made empty initial commit
INFO: Set remote origin to https://github.com/myusername/MyPkg.jl
INFO: Staged 6 files/directories: src/, test/, REQUIRE, README.md, .gitignore, LICENSE
INFO: Committed files generated by PkgTemplates
INFO: Moved temporary package directory into /home/degraafc/.julia/v0.6/
INFO: Finished

julia> run(`git -C $(joinpath(t.dir, "MyPkg")) ls-tree -r --name-only HEAD`)
.gitignore
LICENSE
README.md
REQUIRE
src/MyPkg.jl
test/runtests.jl
```
However, we can also configure a number of keyword arguments to `Template` and
`generate`:

```julia
julia> t = Template(;
           user="myusername",
           license="ISC",
           authors=["Chris de Graaf", "Invenia Technical Computing Corporation"],
           years="2016-2017",
           dir=joinpath(homedir(), "code"),
           julia_version=v"0.5.2",
           requirements=["PkgTemplates"],
           gitconfig=Dict("diff.renames" => true),
           plugins=[
               TravisCI(),
               CodeCov(),
               Coveralls(),
               AppVeyor(),
               GitHubPages(),
           ],
       );

julia> generate("MyPkg", t; force=true, ssh=true)
INFO: Initialized git repo at /tmp/tmpe0dWY5/MyPkg
INFO: Applied git configuration
INFO: Made empty initial commit
INFO: Set remote origin to git@github.com:myusername/MyPkg.jl.git
INFO: Created empty gh-pages branch
INFO: Staged 9 files/directories: src/, test/, REQUIRE, README.md, .gitignore, LICENSE, docs/, .appveyor.yml, .travis.yml
INFO: Committed files generated by PkgTemplates
INFO: Moved temporary package directory into /home/degraafc/code/
INFO: Finished
WARNING: Remember to push all created branches to your remote: git push --all

julia> run(`git -C $(joinpath(t.dir, "MyPkg")) ls-tree -r --name-only HEAD`)
.appveyor.yml
.gitignore
.travis.yml
LICENSE
README.md
REQUIRE
docs/make.jl
docs/src/index.md
src/MyPkg.jl
test/runtests.jl
```

Information on each keyword as well as plugin types can be found in the
[documentation](https://invenia.github.io/PkgTemplates.jl/stable).

If that looks like a lot of work, you can also create templates interactively
with `interactive_template`:

[![asciicast](https://asciinema.org/a/bqBwff05mI7Cl9bz7EqLPMKF8.png)](https://asciinema.org/a/bqBwff05mI7Cl9bz7EqLPMKF8)

And if that's **still** too much work for you, you can call
`interactive_template` with `fast=true` to use default values for everything
but username and plugin selection.

You can also use `generate_interactive` to interactively generate a template and then
immediately use it to create a new package.

## Comparison to PkgDev

`PkgTemplates` is similar in functionality to
[`PkgDev`](https://github.com/JuliaLang/PkgDev.jl)'s `generate` function. However,
`PkgTemplates` offers more customizability in templates and more extensibility via plugins.
For the package registration and release management features that `PkgTemplates` doesn't
include, you are encouraged to use [AttoBot](https://github.com/apps/attobot) instead.

## Contributing

It's extremely easy to extend `PkgTemplates` with new plugins. To get started,
check out the
[plugin development guide](https://invenia.github.io/PkgTemplates.jl/stable/pages/plugin_development.html).