Giter8 -- 把项目布局模板放到 GitHub 上

因为学习或做些小 Demo, 会临时建立一个项目, 项目的布局也常有类似, 不想每次为一个 Maven 项目而执行 mkdir -p example/src/{main,test}/{java,resources}, 或是通过 IDE 来创建, 于是萌生了把自己常用的项目模板放到 GitHub 上的想法. 我们当然可以把直接在 GitHub 上创建一个个项目模板仓库, 想用时只要 git clone 下来, 但克隆的总是与 GitHub 上相应的仓库有关联.

Google 了, 有不少方法能建立项目基本框架, 如

1. 创建 Maven 项目骨架,  mvn archetype:generate -DarchetypeGroupId=.....
2. sbt 的 np 插件可以快速生成项目目录
3. YEOMAN 也有自己的 Generator, 很强大也复杂

再就是现在要介绍的, 比较适合于我的口味的 Giter8, 简单实用, 定义模板更是轻松自如. Giter8 是构建在 sbt launcher 之上的用于从 GitHub 或其他任何 Git 仓库中攫取项目模板的命令行工具. 模板定义简单, 支持变量的提示输入. 下面是安装, 使用, 以及建立自己的模板:

安装 Giter8

只介绍在 Mac OS X 下用 brew 的安装, 其他安装方式请参见 http://www.foundweekends.org/giter8/setup.html(中文版 https://yanbin.gitbooks.io/giter8/content/giter8/setup.html)

$ brew install giter8

安装之后, 可执行文件为 g8, 中英文结合念出来可不那么文雅.

下载模板

这里有一个 giter8 模板的列表, 谁都可以编辑这个文件, 所以我们要是创建了自己的模板也可以加到这个列表中去, 我们选一个来下载, 如 softprops/unfiltered.g8

$ g8 softprops/unfiltered.g8
This template generates an Unfiltered project. By default it depends
on "unfiltered-jetty". For AJP support, set unfiltered_module to
"unfiltered-jetty-ajp".
name [My Web Project]: myweb
version [0.1.0-SNAPSHOT]:
unfiltered_version [ls(unfiltered, unfiltered)]:
Template applied in ./myweb
$ tree myweb
myweb
├── build.sbt
└── src
         ├── main
         │       ├── resources
         │       │   ├── avsl.conf
         │       │   └── www
         │       │             └── css
         │       │                      └── app.css
         │       └── scala
         │                └── Example.scala
         └── test
                  └── scala
                           └── ExampleSpec.scala
8 directories, 5 files

也可以输入 GitHub 上仓库的全路径, 如

$ g8 https://github.com/softprops/unfiltered.g8.git
$ g8 softprops/unfiltered.g8 --name=myweb --version=1.0 --unfiltered_version=200  #提供两部属性可一步到位的创建项目

所以 g8 也允许我们把项目模板托管在别的 git 服务器上.

上面发生了什么? g8 从 softprops/unfiltered.g8 上下载模板定义 src/main/g8, 提示输入的变量定义在 src/main/g8/default.properties 中, 文件内容, 目录都可以使用像 $name$ 来引用输入的值. default.properties 中的 description 字符串用于描述模板, 就是我们见到的 This template generates an Unfiltered project..... 字样.

创建自己的模板

这一步才是我们真正目的所在, 可以参考已有的模板来创建自己的.

1. 一个项目模板就是一个 Git 仓库, 并且 Giter8 模板仓库必须以  .g8 结尾, 例如 yabqiu/basic-maven-archetype.g8
2. 实际的项目模板通常放在仓库的 src/main/g8 目录下, 如果这个目录不存在则仓库根目录取而代之(不建议)
3. 模板目录中的 default.properties 中定义待输入的变量和默认值

default.properties 中又有几个特性值得一提:

1. 属性可以用在任何地方, 如文件内容, 文件名, 甚至是路径 src/$package$
2. name 属性兼做项目创建时的目录名
3. package 属性在用作路径时会进行目录展开, 例如 src/$package$, 并且输入的 package 是 cc.unmi, 那么生成的目录会是 src/cc/unmi/, 而不是字面的 src/cc.unmi
4. description 定义的字符串会首先被 g8 显示出来

由于空目录是无法提交到 Git 上去的, 如果想要模板中有目录 src/main/resources,但暂时没东西往 resources 目录中放, 那么姑且放个点文件 .gitkeep,这样才能把 空目录 提交到 Git 上.

这是本人创造的第一个基本的 Maven  项目的模板, https://github.com/yabqiu/maven-archetype.g8, 可用

$ g8 yabqiu/maven-archetype

另外最后还值得一提的有:

在提交模板到 GitHub 之前可用  g8 file://yabqiu/maven-archetype.g8/ 进行测试. 在使用变量时可进行格式化, 如输入 name 为  My Project 时, 文件中写成 $name;format="normalize"$ 得到 my-project; $organization__packaged$ 放在目录名中将把输入的  cc.unmi 转换为目录 cc/unmi. 还能用 sbt  的 Giter8Plugin 进行模板测试.

更多高级话题请参考: Giter8 -- Combined Pages, 这是已翻译的 Giter8 文档 https://yanbin.gitbooks.io/giter8/content/.

2021-05-11

换了台 Macbook Pro, 系统还是 10.15.7, 在用  brew install giter8 时出现错误

Error: giter8 has been disabled because it fetches unversioned dependencies at runtime!

Google 搜索后无解，不过可以用 sbt new 来使用 giter8 插件

$ sbt new yabqiu/spring-boot-1-starter.g8

和 g8 yabqiu/spring-boot-1-starter.g8  一样的效果，从 github 上的 yabqiu/spring-boot-1-starter.g8 下载模板，输入信息，定制项目。