Merge pull request #203 from aquaproj/package-tag

add the document about package tags

docs/tutorial-extras/package-tag.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 550
+---
+
+# Filter packages with tags
+
+`aqua >= v1.23.0`
+
+[#441](https://github.com/aquaproj/aqua/issues/441) [#1336](https://github.com/aquaproj/aqua/pull/1336)
+
+`aqua cp` and `aqua install` commands support filtering packages with tags.
+
+## Specification
+
+The optional field `tags` can be specified in `aqua.yaml`'s package.
+This field is a string list of tags.
+
+e.g.
+
+```yaml
+---
+registries:
+- type: standard
+  ref: v3.90.0 # renovate: depName=aquaproj/aqua-registry
+packages:
+- name: suzuki-shunsuke/[email protected]
+  tags:
+    - test
+    - foo
+- name: suzuki-shunsuke/[email protected]
+- name: cli/[email protected]
+  tags:
+    - bar
+    - foo
+```
+
+And `aqua install` and `aqua cp` command have the following command line options.
+
+- `--tags (-t)` (string): When this option is set, only packages that have specifed tags are installed. You can specify multiple tags joining with `,` (e.g. `-t ci,test`)
+- `--exclude-tags` (string): When this option is set, packages that have specifed tags aren't installed. You can specify multiple tags joining with `,` (e.g. `-exclude-tags ci,test`)
+
+In case of the above `aqua.yaml`, you can filter packages as the following.
+
+```console
+$ aqua i # Install suzuki-shunsuke/[email protected] and suzuki-shunsuke/[email protected] and cli/[email protected]
+$ aqua i -t test # Install suzuki-shunsuke/[email protected]
+$ aqua i -t foo,bar # Install suzuki-shunsuke/[email protected] and cli/[email protected]
+$ aqua i --exclude-tags test # Install suzuki-shunsuke/[email protected] and cli/[email protected]
+$ aqua i --exclude-tags test -t foo # Install cli/[email protected]
+```
+
+:::caution
+Note that `aqua install` creates symbolic links of all packages regardless tags, so that you can execute all tools by Lazy Install and assure that tools are managed by aqua.
+:::