update document

kcmvp · Jan 23, 2024 · c18143a · c18143a
1 parent 4764bda
commit c18143a
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 89 deletions.
diff --git 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.
 > <img src="https://github.com/kcmvp/gob/blob/main/docs/commit_hook.gif" height="245" width="425">
 
-- Dependency tree 
+
+4: Check project dependency
+```shell
+gob deps
+```
 > <img src="https://github.com/kcmvp/gob/blob/main/docs/dependency_tree.png" height="245" width="425">
 
 
+Please refer [document](./docs/document.md) for details
+
+
 
 ## FAQ
 
diff --git 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