{"id":16475955,"url":"https://github.com/softprops/porteurbars","last_synced_at":"2025-03-21T06:32:18.617Z","repository":{"id":57657223,"uuid":"50895422","full_name":"softprops/porteurbars","owner":"softprops","description":":bike: a tool for sharing portable git hosted project templates","archived":false,"fork":false,"pushed_at":"2018-05-25T13:18:52.000Z","size":660,"stargazers_count":19,"open_issues_count":8,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-17T11:59:59.304Z","etag":null,"topics":["github","handlebars","rust","template-engine"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/softprops.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-02T04:59:37.000Z","updated_at":"2020-07-06T20:39:08.000Z","dependencies_parsed_at":"2022-08-26T04:11:52.856Z","dependency_job_id":null,"html_url":"https://github.com/softprops/porteurbars","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fporteurbars","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fporteurbars/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fporteurbars/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fporteurbars/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softprops","download_url":"https://codeload.github.com/softprops/porteurbars/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244751700,"owners_count":20504246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github","handlebars","rust","template-engine"],"created_at":"2024-10-11T12:40:59.789Z","updated_at":"2025-03-21T06:32:18.126Z","avatar_url":"https://github.com/softprops.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"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)\n\n\n\u003e portable github hosted project templates. less assembly required\n\nPorteurbars is a command line tool for sharing and applying reusable project\ntemplates that remove tedious assembly boilerplate, allowing you to spend less\ntime in the bikeshed and more time on the road.\n\n## Goals\n\n* 0 runtime dependencies\n* use existing and familiar tools: handlebars, github\n* use environment for configuration\n* fast\n* focused feature set\n* fun\n\n## Installation\n\n### homebrew (on osx)\n\n```bash\n$ brew install softprops/tools/porteurbars\n```\n\nIf you want to upgrade to newer versions, use `brew upgrade`\n\n```bash\n$ brew upgrade softprops/tools/porteurbars\n```\n\n### github releases\n\nYou can get up and going by downloading a binary directly from [github releases](https://github.com/softprops/porteurbars/releases).\n\n```bash\n$ cd $HOME/bin\n$ curl -#L \"https://github.com/softprops/porteurbars/releases/download/v0.1.5/porteurbars-$(uname -s)-$(uname -m).tar.gz\" \\\n  | tar -xz -C ~/bin\n$ porteurbars --help\nporteurbars 0.1.5\nportable git hosted project templates\n\nUSAGE:\n    porteurbars [FLAGS] [OPTIONS] \u003crepository\u003e [\u003ctarget\u003e]\n\nFLAGS:\n    -h, --help       Prints help information\n    -k, --keep       disables replacement prompts and keeps local copies of files\n    -V, --version    Prints version information\n    -y, --yes        disables value prompts by accepting all default values\n\nOPTIONS:\n    -b, --base \u003cbase_directory\u003e    directory within \u003crepository\u003e to use as root. defaults to base of repo\n    -r, --rev \u003crevision\u003e           git revision to checkout. defaults to 'master'\n\nARGS:\n    \u003crepository\u003e    uri of template to apply.\n                    example uris\n                    github: user/repo\n                     local: file:///path/to/repo\n                       git: git@github.com:user/repo.git\n    \u003ctarget\u003e        directory to write template output to. defaults to current working directory\n```\n\n## assumptions\n\nPorteurbars templates follow two simple conventions.\n\n1) Porteurbars follows the [12-factor philosophy](http://12factor.net/config) for how to configure your templates.\nPorteurbars assumes a file at the root of a directory called `default.env` exists, containing\nkey value pairs that represent your templates environment variables. When applying a template,\nthis file will be read and the user will be prompted for each key that isn't defined in their\ncurrent environment. This works well on most systems and allows for promptless template execution\nas you can specify and environment before running the program\n\n```bash\n$ FOO=bar BAR=baz porteurbars user/repo target\n```\n\n2) Porteurbars assumes a directory exists called `template` in your template's\nroot directory, next to your `default.env` file. This directory will contain arbitrary\nhandlebars template files representing the your templatized project. Porteurbars will walk\nthrough this directory evaluating templates and copying results to your target directory.\nIf Porteurbars detects the presence of a local file will differences for a given file, you will be\nprompted for whether or not you wish to keep those local changes.\n\n## template hosting\n\nJust upload your templates to [github](https://github.com/). That's it.\n\n![](github.png)\n\n## Usage\n\n### Creating templates\n\nPorteurbars defines a convention for writing templates with only two rules.\n\n1) create file at the root of a directory called `default.env` which stores\nline-oriented key value pairs\n\n```bash\n$ touch default.env\n$ echo \"FOO=bar\" \u003e default.env\n```\n\n2) create a directory called `template` under which you define a set of handlebars templates\n\nPorteurbars supports the notion of rendering templates from file content as well as file paths\nso you can also templatize the location of your template files. See [softprops/mit](https://github.com/softprops/mit) for an example.\n\n```bash\n$ mkdir  template\n$ echo \"Hello {{FOO}}\" \u003e template/hello\n```\n\nPublishing a Porteurbars template is as simple has storing this work in a git repo.\nTo share these templates with others you can simply push this repo to github.\n\n### Applying templates\n\n[Install](#Installation) the porteurbars binary and ensure it's on your execution path.\n\nporteurbars requires one and optionally a second argument.\n\nThe first argument is a reference to a template. The simplest case is using a\ngithub user/repo. By default porteurbars will render this template in the current\nworking directory\n\n\n```bash\n$ porteurbars user/repo\n```\n\nIf this is undesirable, you can provide a path to render into\n\n```bash\n$ porteurbars user/repo target_path\n```\n\nporteurbars will clone this template repo and read the defined template\nvariables from the default.env file. If any of these variables are not defined\nin your env, porteurbars will prompt you for a value falling back on a default\nif you do not provide one.\n\nFinally porteurbars will apply that data to the handlebars templates and write\nall files to the target path.\n\n\n### Composing and collision detection\n\nPorteurbars is designed in a way that let's you compose project templates. What does that mean?\nMost tools will blow away a target directly when applying templates. Porteurbars will not.\nInstead if will detect changes if a template was previously applied and prompt you before\nwriting the new version. Porteurbars also allows you to \"overlay\" different independent\n templates within a project structure which allows you to compose your project templates to\n avoid the one size fits all problem of duplicate but similar templates in the wild.\n\n## Areas of contribution\n\n### handlebars helpers\n\nThe choice of handlebars allows for template level \"helpers\". Currently only a minimal set\nof helpers beyond the built-ins are provided. As a refresher handlebars helper syntax will look something like the example below.\n\n\n```hbs\n{{ upper foo }} {{ lower bar }}\n```\n\nThe table below lists the transformation helpers by name and expected inputs and outputs\n\n| helper     | example in | example out |\n|------------|------------|-------------|\n| upper      | foobar     | FOOBAR     |\n| lower      | FOOBAR     | foobar      |\n| capitalize | foobar     | Foobar      |\n| camel      | foo_bar    | fooBar      |\n| snake      | fooBar     | foo_bar     |\n| dashed     | foo_bar    | foo-bar     |\n\nIt is sometimes useful to conditionally render something based on equality\ncontext data. To support this you may use the `eq` helper.\n\n```hbs\n{{#eq foo \"bar\"}}\nHello equality\n{{else}}\nHello alternative\n{{/eq}}\n```\n\n\nMore are planned in the future, but I plan to let demand drive additions.\n\n### Ideas!\n\nI'd like to hear about your ideas and use cases. It would be useful to assemble a directory\nof known templates. The choice of git(hub) for hosting templates keeps these\ndecentralized which is good but hinders discovery of existing templates.\n\n## Alternatives\n\n### [giter8](https://github.com/foundweekends/giter8)\n\nThis project is heavily influenced by giter8. porteurbars aims to solve some of\nthe issues I've experienced with it. giter8 is a jvm-based cli. To use it, you\nfirst need to install another tool called conscript, which itself requires dependencies\non the underlying engine of sbt ( the scala build tool ), and before that you need to install\na modern version of java's JRE (not to be confused with JDK!).\nThe sum total of this can be hundreds of megabytes you have to download over\nthe internet before your users can get going.\n\nporteurbars comes with a single standalone static binary, weighing in at about, 4M.\n\ngiter8 uses a templating language many are not familiar with, but can get acclimated to,\nauthor templates. porteurbars uses [handlebars templates](http://handlebarsjs.com/) for templating\nin order to be familiar to a larger audience.\n\ngiter8 templates are just git repositories. porteurbars templates are as well.\n\ngiter8 defines a similar set of conventions. You store your templates defaults in a java\nproperties file called default.properties and template source under a mvn-style src/main/g8 directory.\n\nporteurbars opts to read configuration from the environment and, as such, uses a default.env file.\nporteurbars ties to steer away from java's mvn conventions for a simpler directory structure, a \"template\" folder\n\n## [yeoman](http://yeoman.io/)\n\nYeomon is a similar tool that is more focused on providing a scaffolding for template\nauthors to write node.js modules that serve as generators to generate project boilerpate.\n\nporteurbars focuses on a more general audience. To author templates,\nthe only required knowledge is handlebars. Yeomon requires\nyou to install the node runtime and also setup and account on npm to share your\nwork. porteurbars only requires git repositories. For convenience, to facilitate\nsharing on github, it provides convenience for referencing github user repositories (porteurbars user/repo).\n\nYeomon's focus and/or marketing targets front end web development. porteurbars generalizes\nthe problem of templating away boilerplate for any time of project.\n\n\nDoug Tangren (softprops) 2016\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftprops%2Fporteurbars","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftprops%2Fporteurbars","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftprops%2Fporteurbars/lists"}