From c18143a5cb12ef9e57f0a68ee98ab05b14c440ab Mon Sep 17 00:00:00 2001 From: kcmvp Date: Tue, 23 Jan 2024 15:13:47 +0800 Subject: [PATCH] update document --- README.md | 37 +++++++++---------- docs/document.md | 94 +++++++++++++----------------------------------- 2 files changed, 42 insertions(+), 89 deletions(-) diff --git a/README.md b/README.md index de0eeb5..ae25fd8 100644 --- a/README.md +++ b/README.md @@ -38,40 +38,37 @@ or [Gradle](https://gradle.com/) in the **Java** ecosystem. ## Features 1. **Everything is a plugin, simple yet powerful !** -2. Build a tool chain and workflow without line code. -3. Better interaction user experience - -Please refer [document](./docs/document.md) for details +2. Build a tool chain and workflow without a line. +3. Better user experience ## Quick Start -- Install `gob` with below command +1. Install `gob` with below command ```shell go install github.com/kcmvp/gob ``` -- Initialize project with below comman d(in the project home directory) +2. Initialize project with below command(in the project home directory) ```shell gob init ``` +This command will generate two files +>- gob.yaml : `gob` configuration +>- .golangci.yaml: [golangci-lint](https://golangci-lint.run/) configuration. gob supports `golangci-lint` butilin +> These two files need to be checked in with your source code -This command will do below initializations: -> 1. generate gob's configuration [gob.yaml](https://github.com/kcmvp/gob/blob/main/gob.yaml) -> 2. install gob's builtin plugins: [golangci-lint](https://golangci-lint.run/) & [gotestsum](https://github.com/gotestyourself/gotestsum) -> 3. setup three git hooks -> 1. commit-msg -> 2. pre-commit -> 3. pre-push - -*`gob.yaml` and `.golangci.yaml` need to be checkin with your sources code - -## Screenshots - -- Git Hooks +3. Make some changes in your source code and try to commit the code, you will see below screenshot. > -- Dependency tree + +4: Check project dependency +```shell +gob deps +``` > +Please refer [document](./docs/document.md) for details + + ## FAQ diff --git a/docs/document.md b/docs/document.md index 3966a38..eed118b 100644 --- a/docs/document.md +++ b/docs/document.md @@ -1,17 +1,19 @@ -## About gob.yaml configuration -To unleash the powerful capabilities of gob, it is necessary to familiarize yourself with and understand its configuration file: gob.yaml. -This file is to gob what pom.xml is to Maven, or settings.gradle.kts is to Gradle. -All settings about the project are configured in this file. The gob program itself reads this file to perform the corresponding operations. -By combining different configurations, you can almost achieve any powerful function you want. -The following configuration is the configuration of the [gob.yaml](../gob.yaml) project itself (it is eating its own dog food) -This configuration file is divided into two sections: - -- plugins -- exec. +## How gob works +`Gob` takes everything defined in the `gob.yaml` as plugin. +```mermaid +flowchart TD + Gob --> gob.yaml + gob.yaml --> plugin1 + gob.yaml --> plugin2 + gob.yaml --> plugin3 +``` +You just need to tell `gob` 3W(where,when and what) -They respectively define the plugins used in the project and when they will be invoked. -Any tool can be referenced as a plugin in gob, just keep the basic principle in mind: define before use, the same is true in gob! (Same as coding) +1. **Where** : where to download the tool +2. **When** : when to execute to command +2. **What** : what to do with the tool +Below is from `gob` project itself ```yaml exec: commit-msg-hook: ^#[0-9]+:\s*.{10,}$ @@ -22,64 +24,19 @@ exec: - test plugins: golangci-lint: - alias: lint - args: run ./... - url: github.com/golangci/golangci-lint/cmd/golangci-lint@v1.55.2 + alias: lint #When : when issue `gob lint` + args: run ./... #What: execute `golangci-lint run ./...` + url: github.com/golangci/golangci-lint/cmd/golangci-lint@v1.55.2 #Where: where to download the plugin gotestsum: alias: test args: --format testname -- -coverprofile=target/cover.out ./... url: gotest.tools/gotestsum@v1.11.0 ``` - -### Define a plugin - -```yaml - golangci-lint: - alias: lint - args: run ./... - url: github.com/golangci/golangci-lint/cmd/golangci-lint@v1.55.2 -``` -above is a plugin declaration, which define golangci-lint as a plugin in the project. You don't need to manually edit `gob.yaml` to add a plugin. -below command would take all stuffs for you. - -```shell -gob plugin install xxxxxx -``` -Below are the meanings of each section -- golangci-lint : plugin's unique name -- alias: lint : alias of this command, you can use `gob lint` to invoke this plugin -- args: run ./... : The parameters passed to `gob lint` -- url: github.com/golangci/golangci-lint/cmd/golangci-lint@v1.55.2 : Use golangci-lint@v1.55.2 as the plugin -> Compare to `go install`,`gob plugin install` would keep the version as suffix of the binary name. it's an enhanced version `go install` - -### Use a plugin -There are **two** ways to use a defined plugin. Below is the first way, which will be invoked from an external program. Here are the git hooks. -- commit-msg -- pre-commit -- pre-push - -As git local hooks are common requirements, gob implements them as built-in functionalities. -```yaml -exec: - commit-msg-hook: ^#[0-9]+:\s*.{10,}$ // commit message must start with '#' then follows an issue number, the message length must bigger than 10 characters - pre-commit-hook: // execute gob lint & gob test during pre-commit phrase. An error will stop the commit - - lint - - test - pre-push-hook: // execue gob test during pre-push phrase. An error will stop the push - - test -``` -The second way to use declared plugins is invoking plugin directly by using gob. for example if you want to call `golangci-lint@v1.55.2` you can -issue below command -```shell -gob lint -``` +in most cases you don't need to edit the configuration manually. you can achieve this by commands ## Commands -> principles apply to all commands: -> every command must be executed from project root directory - -### init +### gob init ```shell gob init ``` @@ -91,26 +48,26 @@ gob init 6. Generate `gob.yaml` in project root directory 7. Set up git local hooks if current project has been version controlled -### build +### gob build ```shell gob build ``` 1. This command would build binaries in the project.(If there are more than one main method in main package) 2. Final binaries will be built in the ${project_home}/target folder and named the same as go source name which contains main method in main package -### clean +### gob clean ```shell gob clean ``` This command will clean all stuffs in the ${project_home}/target folder -### test +### gob test ```shell gob test ``` This command will test the project and generate coverage report -### lint +### gob lint ```shell gob lint ``` @@ -120,7 +77,7 @@ This command will run lint against project based on the configuration. new-from-rev: HEAD ``` -### gob plugin install (Enhanced version `go install`) +### gob plugin install ```shell gob plugin install ``` @@ -138,8 +95,7 @@ gob plugin install github.com/golangci/golangci-lint/cmd/golangci-lint ```shell gob plugin list ``` -list all the definied plugins in project - +list all the defined plugins in project ### gob deps ```shell