Merge pull request #34 from ageorgou/allow-no-commit

Alternatives to committing

Author: Amelia Wattenberger

README.md

@@ -8,23 +8,23 @@ For a full demo, check out the [githubocto/repo-visualizer-demo](https://github.
 
 ## Inputs
 
-## `output_file`
+### `output_file`
 
 A path (relative to the root of your repo) to where you would like the diagram to live.
 
 For example: images/diagram.svg
 
 Default: diagram.svg
 
-## `excluded_paths`
+### `excluded_paths`
 
 A list of paths to folders to exclude from the diagram, separated by commas.
 
 For example: dist,node_modules
 
 Default: node_modules,bower_components,dist,out,build,eject,.next,.netlify,.yarn,.vscode,package-lock.json,yarn.lock
 
-## `excluded_globs`
+### `excluded_globs`
 
 A semicolon-delimited array of file [globs](https://globster.xyz/) to exclude from the diagram, using [micromatch](https://github.com/micromatch/micromatch) syntax. Provided as an array.
 
@@ -38,32 +38,54 @@ excluded_globs: 'frontend/*.spec.js;**/*.{png,jpg};**/!(*.module).ts'
 # - '**/!(*.module).ts'  # all TS files except module files
 ```
 
-## `root_path`
+### `root_path`
 
 The directory (and its children) that you want to visualize in the diagram, relative to the repository root.
 
 For example: `src/`
 
 Default: `''` (current directory)
 
-## `max_depth`
+### `max_depth`
 
 The maximum number of nested folders to show files within. A higher number will take longer to render.
 
 Default: 9
 
-## `commit_message`
+### `should_push`
+
+Whether to make a new commit with the diagram and push it to the original repository.
+
+Should be a boolean value, i.e. `true` or `false`. See `commit_message` and `branch` for how to customise the commit.
+
+Default: `true`
+
+### `commit_message`
 
 The commit message to use when updating the diagram. Useful for skipping CI. For example: `Updating diagram [skip ci]`
 
 Default: `Repo visualizer: updated diagram`
 
-## `branch`
+### `branch`
 
 The branch name to push the diagram to (branch will be created if it does not yet exist).
 
 For example: `diagram`
 
+### `artifact_name`
+
+The name of an [artifact](https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts) to create containing the diagram.
+
+If unspecified, no artifact will be created.
+
+Default: `''` (no artifact)
+
+## Outputs
+
+### `svg`
+
+The contents of the diagram as text. This can be used if you don't want to handle new files.
+
 ## Example usage
 
 You'll need to run the `actions/checkout` Action beforehand, to check out the code.
@@ -77,3 +99,34 @@ You'll need to run the `actions/checkout` Action beforehand, to check out the co
     output_file: "images/diagram.svg"
     excluded_paths: "dist,node_modules"
 ```
+
+
+## Accessing the diagram
+
+By default, this action will create a new commit with the diagram on the specified branch.
+
+If you want to avoid new commits, you can create an artifact to accompany the workflow run,
+by specifying an `artifact_name`. You can then download the diagram using the
+[`actions/download-artifact`](https://github.com/marketplace/actions/download-a-build-artifact)
+action from a later step in your workflow,
+or by using the [GitHub API](https://docs.github.com/en/rest/reference/actions#artifacts).
+
+Example:
+```yaml
+- name: Update diagram
+  id: make_diagram
+  uses: githubocto/[email protected]
+  with:
+    output_file: "images/diagram.svg"
+    artifact_name: my-diagram
+- name: Get artifact
+  uses: actions/download-artifact@v2
+  with:
+    name: my-diagram
+    path: downloads
+  # Diagram now available at downloads/images/diagram.svg
+```
+Note that this will still also create a commit, unless you specify `should_push: false`!
+
+Alternatively, the SVG description of the diagram is available in the `svg` output,
+which you can refer to in your workflow as e.g. `${{ steps.make_diagram.outputs.svg }}`.

action.yml

@@ -23,6 +23,17 @@ inputs:
   branch:
     description: "The branch name to push the diagram to (branch will be created if it does not yet exist). For example: diagram"
     required: false
+  should_push:
+    description: "Whether to push the new commit back to the repository. Must be true or false. Default: true"
+    required: false
+    default: true
+  artifact_name:
+    description: "If given, the name of an artifact to be created containing the diagram. Default: don't create an artifact."
+    required: false
+    default: ''
+outputs:
+  svg:
+    description: "The diagram contents as text"
 runs:
   using: "node12"
   main: "index.js"