porteurbars

可移植的 GitHub 主机项目模板。减少组装需求

Porteurbars 是一个用于共享和应用可重用项目模板的命令行工具，它可以消除繁琐的组装样板，让您有更多时间专注于项目本身。

目标

• 0 运行时依赖
• 使用现有和熟悉的工具：handlebars、github
• 使用环境进行配置
• 快速
• 专注的功能集
• 有趣

安装

homebrew (在 osx 上)

$ brew install softprops/tools/porteurbars

如果您想升级到新版本，请使用 brew upgrade

$ brew upgrade softprops/tools/porteurbars

GitHub 发布

您可以直接从 GitHub 发布 下载二进制文件来开始使用。

$ cd $HOME/bin
$ curl -#L "https://github.com/softprops/porteurbars/releases/download/v0.1.4/porteurbars-$(uname -s)-$(uname -m).tar.gz" \
  | tar -xz -C ~/bin
$ porteurbars --help
porteurbars 0.1.4
portable git hosted project templates

USAGE:
    porteurbars [FLAGS] [OPTIONS] <repository> [<target>]

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 <base_directory>    directory within <repository> to use as root. defaults to base of repo
    -r, --rev <revision>           git revision to checkout. defaults to 'master'

ARGS:
    <repository>    uri of template to apply.
                    example uris
                    github: user/repo
                     local: file:///path/to/repo
                       git: [email protected]:user/repo.git
    <target>        directory to write template output to. defaults to current working directory

假设

Porteurbars 模板遵循两个简单的约定。

1. Porteurbars 遵循 12 个因素哲学 来配置模板。Porteurbars 假设目录根目录下存在一个名为 default.env 的文件，其中包含代表模板环境变量的键值对。当应用模板时，该文件将被读取，用户将被提示输入当前环境中未定义的每个键。这在大多数系统中都行之有效，并且可以在运行程序之前指定环境，从而实现无需提示的模板执行

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

2. Porteurbars 假设在你的模板根目录下存在一个名为 template 的目录，该目录位于你的 default.env 文件旁边。这个目录将包含表示你的模板化项目的任意 handlebars 模板文件。Porteurbars 将遍历这个目录，评估模板并将结果复制到你的目标目录。如果 Porteurbars 检测到给定文件的本地文件存在差异，你将被提示是否保留这些本地更改。

模板托管

只需将你的模板上传到 github。就是这样。

用法

创建模板

Porteurbars 定义了编写模板的两个规则。

1. 在目录根目录创建一个名为 default.env 的文件，该文件存储面向行的键值对

$ touch default.env
$ echo "FOO=bar" > default.env

2. 在 template 目录下创建一个目录，在其中定义一组 handlebars 模板

Porteurbars 支持从文件内容以及文件路径渲染模板的概念，因此你也可以模板化模板文件的存储位置。请参阅 softprops/mit 的示例。

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

发布 Porteurbars 模板就像将这项工作存储在 git 仓库中一样简单。要与他人共享这些模板，你可以简单地将此仓库推送到 github。

应用模板

安装 porteurbars 二进制文件，并确保它在你的执行路径上。

porteurbars 需要一个参数，可选第二个参数。

第一个参数是模板的引用。最简单的情况是使用 github 用户/仓库。默认情况下，porteurbars 将在当前工作目录中渲染此模板

$ porteurbars user/repo

如果你不希望这样做，你可以提供一个路径进行渲染

$ porteurbars user/repo target_path

porteurbars 将克隆此模板仓库，并从默认.env 文件中读取定义的模板变量。如果其中任何变量在你的 env 中未定义，porteurbars 将提示你输入值，如果没有提供值，则回退到默认值。

最后，porteurbars 将将这些数据应用于 handlebars 模板，并将所有文件写入目标路径。

组合和碰撞检测

Porteurbars 是以允许你组合项目模板的方式进行设计的。这意味着什么？大多数工具在应用模板时都会清除目标目录。Porteurbars 不会这样做。相反，它会检测是否有模板被之前应用，并在写入新版本之前提示你。Porteurbars 还允许你在项目结构内“叠加”不同的独立模板，这使得你可以组合你的项目模板，以避免野外中重复但类似的模板的“一刀切”问题。

贡献领域

handlebars 辅助函数

选择 handlebars 允许在模板级别使用“辅助函数”。目前只提供了一组超出内置的辅助函数。作为复习，handlebars 辅助函数的语法将类似于下面的示例。

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

下表列出了按名称和预期输入输出列表的转换辅助函数。

有时根据等价上下文数据有条件地渲染某些内容是有用的。为此，你可以使用 eq 辅助函数。

{{#eq foo "bar"}}
Hello equality
{{else}}
Hello alternative
{{/eq}}

未来计划添加更多，但我计划让需求驱动添加。

想法！

我想了解您的想法和用例。组织一个已知模板的目录会有所帮助。选择git(hub)托管模板使其分散化，这很好，但阻碍了对现有模板的发现。

替代方案

giter8

本项目深受giter8的影响。porteurbars旨在解决我在使用中遇到的一些问题。giter8是一个基于jvm的命令行工具。要使用它，您首先需要安装一个名为conscript的工具，该工具本身又依赖于sbt（Scala构建工具）的底层引擎，并且在此之前，您需要安装Java的JRE的现代版本（不要与JDK混淆！）这一过程总共可能需要下载数百兆的文件，您的用户才能开始使用。

porteurbars附带一个单独的独立静态二进制文件，大小约为4M。

giter8使用许多人不熟悉的模板语言，但可以适应，用于编写作者模板。porteurbars使用handlebars模板进行模板化，以便更大范围的受众能够熟悉。

giter8模板只是git仓库。porteurbars模板也是如此。

giter8定义了一套类似的约定。您将模板默认值存储在一个名为default.properties的Java属性文件中，模板源代码位于mvn风格的src/main/g8目录下。

porteurbars选择从环境读取配置，因此使用默认.env文件。porteurbars试图避免Java的mvn约定，以实现更简单的目录结构，一个“模板”文件夹。

yeoman

Yeomon是一个类似的工具，它更专注于为模板作者提供脚手架，以便编写Node.js模块，这些模块作为生成器用于生成项目样板。

porteurbars面向更广泛的受众。要编写模板，只需要了解handlebars。Yeomon要求您安装Node运行时，并在npm上设置账户以共享您的作品。porteurbars仅要求git仓库。为了方便起见，为了便于在GitHub上共享，它提供了引用GitHub用户仓库（porteurbars用户/仓库名）的便利。

Yeomon的关注点和/或营销目标是前端Web开发。porteurbars将模板化问题泛化为任何类型项目的样板问题。

Doug Tangren（softprops）2016