https://github.com/softprops/porteurbars

:bike: a tool for sharing portable git hosted project templates
https://github.com/softprops/porteurbars

github handlebars rust template-engine

Last synced: 3 months ago
JSON representation

:bike: a tool for sharing portable git hosted project templates

• Host: GitHub
• URL: https://github.com/softprops/porteurbars
• Owner: softprops
• License: mit
• Created: 2016-02-02T04:59:37.000Z (almost 9 years ago)
• Default Branch: master
• Last Pushed: 2018-05-25T13:18:52.000Z (over 6 years ago)
• Last Synced: 2024-10-11T12:41:09.023Z (3 months ago)
• Topics: github, handlebars, rust, template-engine
• Language: Rust
• Homepage:
• Size: 645 KB
• Stars: 19
• Watchers: 4
• Forks: 5
• Open Issues: 8
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# porteurbars [![Build Status](https://travis-ci.org/softprops/porteurbars.svg?branch=master)](https://travis-ci.org/softprops/porteurbars) ![version](https://img.shields.io/github/release/softprops/porteurbars.svg) [![license](https://img.shields.io/github/license/softprops/porteurbars.svg)](LICENSE)

> portable github hosted project templates. less assembly required

Porteurbars is a command line tool for sharing and applying reusable project

templates that remove tedious assembly boilerplate, allowing you to spend less

time in the bikeshed and more time on the road.

## Goals

* 0 runtime dependencies

* use existing and familiar tools: handlebars, github

* use environment for configuration

* fast

* focused feature set

* fun

## Installation

### homebrew (on osx)

```bash

$ brew install softprops/tools/porteurbars

```

If you want to upgrade to newer versions, use `brew upgrade`

```bash

$ brew upgrade softprops/tools/porteurbars

```

### github releases

You can get up and going by downloading a binary directly from [github releases](https://github.com/softprops/porteurbars/releases).

```bash

$ cd $HOME/bin

$ curl -#L "https://github.com/softprops/porteurbars/releases/download/v0.1.5/porteurbars-$(uname -s)-$(uname -m).tar.gz" \

  | tar -xz -C ~/bin

$ porteurbars --help

porteurbars 0.1.5

portable git hosted project templates

USAGE:

    porteurbars [FLAGS] [OPTIONS]  []

FLAGS:

    -h, --help       Prints help information

    -k, --keep       disables replacement prompts and keeps local copies of files

    -V, --version    Prints version information

    -y, --yes        disables value prompts by accepting all default values

OPTIONS:

    -b, --base     directory within  to use as root. defaults to base of repo

    -r, --rev            git revision to checkout. defaults to 'master'

ARGS:

        uri of template to apply.

                    example uris

                    github: user/repo

                     local: file:///path/to/repo

                       git: [email protected]:user/repo.git

            directory to write template output to. defaults to current working directory

```

## assumptions

Porteurbars templates follow two simple conventions.

1) Porteurbars follows the [12-factor philosophy](http://12factor.net/config) for how to configure your templates.

Porteurbars assumes a file at the root of a directory called `default.env` exists, containing

key value pairs that represent your templates environment variables. When applying a template,

this file will be read and the user will be prompted for each key that isn't defined in their

current environment. This works well on most systems and allows for promptless template execution

as you can specify and environment before running the program

```bash

$ FOO=bar BAR=baz porteurbars user/repo target

```

2) Porteurbars assumes a directory exists called `template` in your template's

root directory, next to your `default.env` file. This directory will contain arbitrary

handlebars template files representing the your templatized project. Porteurbars will walk

through this directory evaluating templates and copying results to your target directory.

If Porteurbars detects the presence of a local file will differences for a given file, you will be

prompted for whether or not you wish to keep those local changes.

## template hosting

Just upload your templates to [github](https://github.com/). That's it.

![](github.png)

## Usage

### Creating templates

Porteurbars defines a convention for writing templates with only two rules.

1) create file at the root of a directory called `default.env` which stores

line-oriented key value pairs

```bash

$ touch default.env

$ echo "FOO=bar" > default.env

```

2) create a directory called `template` under which you define a set of handlebars templates

Porteurbars supports the notion of rendering templates from file content as well as file paths

so you can also templatize the location of your template files. See [softprops/mit](https://github.com/softprops/mit) for an example.

```bash

$ mkdir  template

$ echo "Hello {{FOO}}" > template/hello

```

Publishing a Porteurbars template is as simple has storing this work in a git repo.

To share these templates with others you can simply push this repo to github.

### Applying templates

[Install](#Installation) the porteurbars binary and ensure it's on your execution path.

porteurbars requires one and optionally a second argument.

The first argument is a reference to a template. The simplest case is using a

github user/repo. By default porteurbars will render this template in the current

working directory

```bash

$ porteurbars user/repo

```

If this is undesirable, you can provide a path to render into

```bash

$ porteurbars user/repo target_path

```

porteurbars will clone this template repo and read the defined template

variables from the default.env file. If any of these variables are not defined

in your env, porteurbars will prompt you for a value falling back on a default

if you do not provide one.

Finally porteurbars will apply that data to the handlebars templates and write

all files to the target path.

### Composing and collision detection

Porteurbars is designed in a way that let's you compose project templates. What does that mean?

Most tools will blow away a target directly when applying templates. Porteurbars will not.

Instead if will detect changes if a template was previously applied and prompt you before

writing the new version. Porteurbars also allows you to "overlay" different independent

 templates within a project structure which allows you to compose your project templates to

 avoid the one size fits all problem of duplicate but similar templates in the wild.

## Areas of contribution

### handlebars helpers

The choice of handlebars allows for template level "helpers". Currently only a minimal set

of helpers beyond the built-ins are provided. As a refresher handlebars helper syntax will look something like the example below.

```hbs

{{ upper foo }} {{ lower bar }}

```

The table below lists the transformation helpers by name and expected inputs and outputs

| helper     | example in | example out |

|------------|------------|-------------|

| upper      | foobar     | FOOBAR     |

| lower      | FOOBAR     | foobar      |

| capitalize | foobar     | Foobar      |

| camel      | foo_bar    | fooBar      |

| snake      | fooBar     | foo_bar     |

| dashed     | foo_bar    | foo-bar     |

It is sometimes useful to conditionally render something based on equality

context data. To support this you may use the `eq` helper.

```hbs

{{#eq foo "bar"}}

Hello equality

{{else}}

Hello alternative

{{/eq}}

```

More are planned in the future, but I plan to let demand drive additions.

### Ideas!

I'd like to hear about your ideas and use cases. It would be useful to assemble a directory

of known templates. The choice of git(hub) for hosting templates keeps these

decentralized which is good but hinders discovery of existing templates.

## Alternatives

### [giter8](https://github.com/foundweekends/giter8)

This project is heavily influenced by giter8. porteurbars aims to solve some of

the issues I've experienced with it. giter8 is a jvm-based cli. To use it, you

first need to install another tool called conscript, which itself requires dependencies

on the underlying engine of sbt ( the scala build tool ), and before that you need to install

a modern version of java's JRE (not to be confused with JDK!).

The sum total of this can be hundreds of megabytes you have to download over

the internet before your users can get going.

porteurbars comes with a single standalone static binary, weighing in at about, 4M.

giter8 uses a templating language many are not familiar with, but can get acclimated to,

author templates. porteurbars uses [handlebars templates](http://handlebarsjs.com/) for templating

in order to be familiar to a larger audience.

giter8 templates are just git repositories. porteurbars templates are as well.

giter8 defines a similar set of conventions. You store your templates defaults in a java

properties file called default.properties and template source under a mvn-style src/main/g8 directory.

porteurbars opts to read configuration from the environment and, as such, uses a default.env file.

porteurbars ties to steer away from java's mvn conventions for a simpler directory structure, a "template" folder

## [yeoman](http://yeoman.io/)

Yeomon is a similar tool that is more focused on providing a scaffolding for template

authors to write node.js modules that serve as generators to generate project boilerpate.

porteurbars focuses on a more general audience. To author templates,

the only required knowledge is handlebars. Yeomon requires

you to install the node runtime and also setup and account on npm to share your

work. porteurbars only requires git repositories. For convenience, to facilitate

sharing on github, it provides convenience for referencing github user repositories (porteurbars user/repo).

Yeomon's focus and/or marketing targets front end web development. porteurbars generalizes

the problem of templating away boilerplate for any time of project.

Doug Tangren (softprops) 2016