Merge pull request #89 from guitarrapc/patch-1

Update README.md

Author: srz-zumix

README.md

@@ -2,9 +2,11 @@
 [![build-test](https://github.com/DeNA/setup-job-workspace-action/actions/workflows/test.yml/badge.svg)](https://github.com/DeNA/setup-job-workspace-action/actions/workflows/test.yml)
 
 # setup-job-workspace-action
+
 An action creating a virtual workspace directory for each job. It is useful when using self-hosted runner with large size of repository.
 
 ## Usage
+
 ```yaml
 jobs:
   default:
@@ -62,11 +64,37 @@ jobs:
       # ... your build steps
 ```
 
+### Example
+
+Below is [Unity](https://unity.com/) build example. Unity build takes a long time if missing Library, so we want to keep it between jobs. This action can solve this problem by creating a virtual workspace directory per runner & workflow basis.
+
+```yaml
+jobs:
+  unity:
+    runs-on: [self-hosted]
+    steps:
+      - name: Switch workspace
+        uses: DeNA/setup-job-workspace-action@v2
+        with:
+          # Change path by build option
+          suffix: "${{ (inputs.enable_XXX && '-XXX') || '' }}"
+      - uses: actions/checkout@v3
+        with:
+          # Clean everything by build option
+          clean: ${{ inputs.clean || false }}
+      - name: Git clean without Library
+        run: git clean -xffd --exclude Library
+      # ... your build steps
+```
+
 ### Options
+
 See [action.yml](./action.yml)
 
 ## Notice
+
 ### Default workspace name is different for older runner version.
+
 `workspace-name` default is `${workflow-yaml-name}-${job-name}`, but when self-hosted runner version is older than [actions/[email protected]](https://github.com/actions/runner/releases/tag/v2.300.0) defalut is `${workflow-name}-${job-name}`.
 
 This defference comes from technical reason that how to get workflow yaml name. First, try to get yaml name from `GITHUB_WORKFLOW_REF` environment variable that exposed from runner version v2.300.0
@@ -75,6 +103,7 @@ This defference comes from technical reason that how to get workflow yaml name.
 If you want to keep the same workspace name between different versions of the runner or for future version upgrades, specify the `workspace-name` option explicitly.
 
 ## How it works
+
 GitHub Actions runner only has one workspace directory per repository ($GITHUB_WORKSPACE). That path is defined by the repository name, for example the workspace path of this repository is `/home/runner/work/setup-job-workspace-action/setup-job-workspace-action` in GitHub hosted Ubuntu runner.
 
 This action creates a new virtual workspace directory and replaces $GITHUB_WORKSPACE as symlink that target to it. So GitHub Actions runner treats the new virtual workspace as a job workspace, it is possible to separate workspace for each job like Jenkins by creating a virtual workspace per job.
@@ -98,6 +127,7 @@ mv ${GITHUB_WORKSPACE}.bak ${GITHUB_WORKSPACE}
 ```
 
 ## Why need it
+
 When using GitHub-hosted runner, a new VM is given for each job. On the other hand, self-hosted runner runs on the same machine, a single workspace($GITHUB_WORKSPACE) is used for jobs that in the same repository. `actions/checkout` cleans workspace before checkout using `git clean -ffdx` in default, it works fine for a normal sized repository.
 
 However, there are some problems when repository size is too large. Some of the workflows will download large binary tools for a current build and output large build cache for the next build, so `actions/checkout` default cleaning is inefficient sometimes.
@@ -107,6 +137,7 @@ And also some git options like `sparse checkout` are very efficient if your job
 This problem can be solved if each job has its own workspace and can reuse `.git/` created by advanced git options. Jenkins has been successful in this way for a long time. `setup-job-workspace-action` also realizes it on GitHub Actions.
 
 ## Development
+
 ```bash
 npm run build
 npm run lint