From 335f001567174a297b4c8889a06275bb4e212741 Mon Sep 17 00:00:00 2001 From: Tonye Jack Date: Sat, 29 Oct 2022 15:48:36 -0600 Subject: [PATCH] chore: updated docs --- .github/ISSUE_TEMPLATE/bug_report.yaml | 9 +++ .github/workflows/update-readme.yml | 5 ++ README.md | 102 ++++++++++++++----------- action.yml | 78 +++++++++---------- 4 files changed, 109 insertions(+), 85 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 4fdabc09..dd484b31 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -70,6 +70,15 @@ body: attributes: label: Relevant log output description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. + placeholder: | + ### This can be done by: + - #### Re-running the workflow with debug logging enabled. + ![Screen Shot 2022-10-26 at 2 30 41 PM](https://user-images.githubusercontent.com/17484350/198131404-2ff30c05-bf5f-4670-94f7-ab28bbfad4f5.png) + + ### AND + + - #### Downloading the log archive + ![Screen Shot 2022-10-26 at 2 33 04 PM](https://user-images.githubusercontent.com/17484350/198131757-85715722-6a8d-4125-85af-76954420f28b.png) render: shell - type: textarea attributes: diff --git a/.github/workflows/update-readme.yml b/.github/workflows/update-readme.yml index 1b276613..e263810e 100644 --- a/.github/workflows/update-readme.yml +++ b/.github/workflows/update-readme.yml @@ -13,6 +13,11 @@ jobs: with: fetch-depth: 0 + - name: Run auto-doc + uses: tj-actions/auto-doc@v1.4.1 + with: + col_max_words: 12 + - name: Run test uses: tj-actions/remark@v3 diff --git a/README.md b/README.md index efef7142..a05fbece 100644 --- a/README.md +++ b/README.md @@ -102,7 +102,7 @@ Support this project with a :star: [buymeacoffee-shield]: https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png -## Outputs +## Useful Acronyms | Acronym | Meaning | |:---------:|:------------:| @@ -115,54 +115,64 @@ Support this project with a :star: | U | Unmerged | | X | Unknown | -| Output | type | example | description | -|:----------------------------------:|:--------:|:--------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| -| any\_changed | `string` | `true` OR `false` | Returns `true` when any
of the filenames provided using
the `files` input has changed. If no `files` have been specified,
an empty string `''` is returned.
i.e. *using a combination of all added,
copied, modified and renamed files (ACMR)* | -| only\_changed | `string` | `true` OR `false` | Returns `true` when only
files provided using
the `files` input has changed. If no `files` have been specified,
an empty string `''` is returned.
i.e. *using a combination of all added,
copied, modified and renamed files (ACMR)* | -| other\_changed\_files | `string` | `'new.txt path/to/file.png ...'` | Returns all other changed files
not listed in the files input
i.e. *using a combination of all added,
copied, modified and renamed files (ACMR)* | -| any\_modified | `string` | `true` OR `false` | Returns `true` when any
of the filenames provided using
the `files` input has been modified. If no `files` have been specified,
an empty string `''` is returned.
i.e. *using a combination of all added,
copied, modified, renamed, and deleted files (ACMRD)* | -| only\_modified | `string` | `true` OR `false` | Returns `true` when only
files provided using
the `files` input has been modified. If no `files` have been specified,
an empty string `''` is returned.(ACMRD) | -| other\_modified\_files | `string` | `'new.txt path/to/file.png ...'` | Returns all other modified files
not listed in the files input
i.e. *a combination of all added,
copied, modified, and deleted files (ACMRD)* | -| any\_deleted | `string` | `true` OR `false` | Returns `true` when any
of the filenames provided using
the `files` input has been deleted. If no `files` have been specified,
an empty string `''` is returned. (D) | -| only\_deleted | `string` | `true` OR `false` | Returns `true` when only
files provided using
the `files` input has been deleted. If no `files` have been specified,
an empty string `''` is returned. (D) | -| other\_deleted\_files | `string` | `'new.txt path/to/file.png ...'` | Returns all other deleted files
not listed in the files input
i.e. *a combination of all deleted files (D)* | -| all\_changed\_files | `string` | `'new.txt path/to/file.png ...'` | Returns all changed files
i.e. *a combination of all added,
copied, modified and renamed files (ACMR)* | -| all\_modified\_files | `string` | `'new.txt path/to/file.png ...'` | Returns all changed files
i.e. *a combination of all added,
copied, modified, renamed and deleted files (ACMRD)* | -| all\_changed\_and\_modified\_files | `string` | `'new.txt path/to/file.png ...'` | Returns all changed
and modified files
i.e. *a combination of (ACMRDTUX)* | -| all\_old\_new\_renamed\_files | `string` | `'old name.txt,new name.txt old name 2.txt,new name 2.txt...'` | Returns only files that are Renamed and list their old and new names.
NOTE: This requires setting `include_all_old_new_renamed_files` to `true` (R) | -| added\_files | `string` | `'new.txt path/to/file.png ...'` | Returns only files that are Added (A) | -| copied\_files | `string` | `'new.txt path/to/file.png ...'` | Returns only files that are Copied (C) | -| deleted\_files | `string` | `'new.txt path/to/file.png ...'` | Returns only files that are Deleted (D) | -| modified\_files | `string` | `'new.txt path/to/file.png ...'` | Returns only files that are Modified (M) | -| renamed\_files | `string` | `'new.txt path/to/file.png ...'` | Returns only files that are Renamed (R) | -| type\_changed\_files | `string` | `'new.txt path/to/file.png ...'` | Returns only files that have their file type changed (T) | -| unmerged\_files | `string` | `'new.txt path/to/file.png ...'` | Returns only files that are Unmerged (U) | -| unknown\_files | `string` | `'new.txt path/to/file.png ...'` | Returns only files that are Unknown (X) | +## Outputs + + + +| OUTPUT | TYPE | DESCRIPTION | +|--------------------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| added_files | string | Returns only files that are Added (A). | +| all_changed_and_modified_files | string | Returns all changed and modified files i.e. *a combination of (ACMRDTUX)* | +| all_changed_files | string | Returns all changed files i.e. *a combination of all added, copied, modified
and renamed files (ACMR)* | +| all_modified_files | string | Returns all changed files i.e. *a combination of all added, copied, modified,
renamed and deleted files (ACMRD)*. | +| all_old_new_renamed_files | string | Returns only files that are Renamed and list their old and new
names. **NOTE:** This requires setting `include_all_old_new_renamed_files` to `true` (R) | +| any_changed | string | Returns `true` when any of the filenames provided using the `files` input
has changed. If no `files` have been specified,an empty string `''` is
returned. i.e. *using a combination of all added, copied, modified and renamed
files (ACMR)*. | +| any_deleted | string | Returns `true` when any of the filenames provided using the `files` input
has been deleted. If no `files` have been specified,an empty string `''`
is returned. (D) | +| any_modified | string | Returns `true` when any of the filenames provided using the `files` input
has been modified. If no `files` have been specified,an empty string `''`
is returned. i.e. *using a combination of all added, copied, modified, renamed,
and deleted files (ACMRD)*. | +| copied_files | string | Returns only files that are Copied (C). | +| deleted_files | string | Returns only files that are Deleted (D). | +| modified_files | string | Returns only files that are Modified (M). | +| only_changed | string | Returns `true` when only files provided using the `files` input has changed.
If no `files` have been specified,an empty string `''` is returned. i.e.
*using a combination of all added, copied, modified and renamed files (ACMR)*.
| +| only_deleted | string | Returns `true` when only files provided using the `files` input has been
deleted. If no `files` have been specified,an empty string `''` is returned.
(D) | +| only_modified | string | Returns `true` when only files provided using the `files` input has been
modified. If no `files` have been specified,an empty string `''` is returned.(ACMRD).
| +| other_changed_files | string | Returns all other changed files not listed in the files input i.e.
*using a combination of all added, copied, modified and renamed files (ACMR)*.
| +| other_deleted_files | string | Returns all other deleted files not listed in the files input i.e.
*a combination of all deleted files (D)* | +| other_modified_files | string | Returns all other modified files not listed in the files input i.e.
*a combination of all added, copied, modified, and deleted files (ACMRD)* | +| renamed_files | string | Returns only files that are Renamed (R). | +| type_changed_files | string | Returns only files that have their file type changed (T). | +| unknown_files | string | Returns only files that are Unknown (X). | +| unmerged_files | string | Returns only files that are Unmerged (U). | + + ## Inputs -| Input | type | required | default | description | -|:--------------------------------------:|:----------------------:|:--------:|:-------------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| -| separator | `string` | `false` | `' '` | Split character for output strings | -| include\_all\_old\_new\_renamed\_files | `boolean` | `false` | `false` | Include `all_old_new_renamed_files` output. Note this can generate a large output See: [#501](https://github.com/tj-actions/changed-files/issues/501). | -| old\_new\_separator | `string` | `false` | `','` | Split character for old and new filename pairs | -| old\_new\_files\_separator | `string` | `false` | `' '` | Split character for multiple old and new filename pairs | -| files | `string` OR `string[]` | `false` | | Check for changes
using only these
list of file(s)
(Defaults to the
entire repo)
**NOTE:** Multiline file/directory patterns
should not include qoutes.
| -| files\_separator | `string` | `false` | `'\n'` | Separator used to split the
`files` input | -| files\_from\_source\_file | `string` | `false` | | Source file(s)
used to populate
the `files` input | -| files\_ignore | `string` | `false` | | Ignore changes to these file(s)
**NOTE:** Multiline file/directory patterns
should not include qoutes.
| -| files\_ignore\_separator | `string` | `false` | `'\n'` | Separator used to split the
`files-ignore` input | -| files\_ignore\_from\_source\_file | `string` | `false` | | Source file(s)
used to populate
the `files_ignore` input | -| sha | `string` | `true` | `${{ github.sha }}` | Specify a different
commit SHA
used for
comparing changes | -| base\_sha | `string` | `false` | | Specify a different
base commit SHA
used for
comparing changes | -| path | `string` | `false` | `'.'` | Relative path under
`GITHUB_WORKSPACE`
to the repository | -| quotepath | `boolean` | `false` | `true` | Output filenames completely verbatim by setting this to `false` | -| diff\_relative | `boolean` | `false` | | Exclude changes outside the current directory and show pathnames relative to it. **NOTE:** This requires you to specify the top level directory via the `path` input. | -| dir\_names | `boolean` | `false` | `false` | Output unique changed directories instead of filenames.
**NOTE:** This returns `.` for
changed files located in the root of the project. | -| json | `boolean` | `false` | `false` | Output changed files in JSON format which can be used for [matrix jobs](https://github.com/tj-actions/changed-files/blob/main/.github/workflows/manual-matrix-test.yml). | -| since | `string` | `false` | | Get changed files for commits whose timestamp is older than the given time. | -| until | `string` | `false` | | Get changed files for commits whose timestamp is earlier than the given time. | -| max\_fetch\_depth | `string` | `false` | `120` | Max limit for fetching branch history. **NOTE**: This can be adjusted to resolve errors with insufficient history. | + + +| INPUT | TYPE | REQUIRED | DEFAULT | DESCRIPTION | +|-----------------------------------|--------|----------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| base_sha | string | false | | Specify a different base commit SHA used for comparing changes | +| diff_relative | string | false | | Exclude changes outside the current directory and show pathnames relative to it.
**NOTE:** This requires you to specify the top level directory via the
`path` input. | +| dir_names | string | false | `"false"` | Output unique changed directories instead of filenames. **NOTE:** This returns `.` for
changed files located in the root of the project. | +| files | string | false | | File and directory patterns to detect changes using only these list of
file(s) (Defaults to the entire repo) **NOTE:** Multiline file/directory patterns should not
include qoutes. | +| files_from_source_file | string | false | | Source file(s) used to populate the `files` input. | +| files_ignore | string | false | | Ignore changes to these file(s) **NOTE:** Multiline file/directory patterns should not include
qoutes. | +| files_ignore_from_source_file | string | false | | Source file(s) used to populate the `files_ignore` input | +| files_ignore_separator | string | false | `"\n"` | Separator used to split the `files-ignore` input | +| files_separator | string | false | `"\n"` | Separator used to split the `files` input | +| include_all_old_new_renamed_files | string | false | `"false"` | Include `all_old_new_renamed_files` output. Note this can generate a large output See: [#501](https://github.com/tj-actions/changed-files/issues/501).
| +| json | string | false | `"false"` | Output list of changed files in a JSON formatted string which can
be used for matrix jobs. | +| max_fetch_depth | string | false | `"120"` | Max limit for fetching branch history. **NOTE**: This can be adjusted to
resolve errors with insufficient history. | +| old_new_files_separator | string | false | `" "` | Split character for multiple old and new filename pairs. | +| old_new_separator | string | false | `","` | Split character for old and new filename pairs. | +| path | string | false | `"."` | Specify a relative path under `$GITHUB_WORKSPACE` to locate the repository. | +| quotepath | string | false | `"true"` | Use non ascii characters to match files and output the filenames completely
verbatim by setting this to `false` | +| separator | string | false | `" "` | Split character for output strings | +| sha | string | true | `"${{ github.sha }}"` | Specify a different commit SHA used for comparing changes | +| since | string | false | | Get changed files for commits whose timestamp is older than the given
time. | +| until | string | false | | Get changed files for commits whose timestamp is earlier than the given
time. | + + ## Examples diff --git a/action.yml b/action.yml index 48e4693d..6b36ab66 100644 --- a/action.yml +++ b/action.yml @@ -8,73 +8,73 @@ inputs: required: false default: " " include_all_old_new_renamed_files: - description: "Include all_old_new_renamed_files output. Note this can generate a large debug output See: #501." + description: "Include `all_old_new_renamed_files` output. Note this can generate a large output See: [#501](https://github.com/tj-actions/changed-files/issues/501)." required: false default: "false" old_new_separator: - description: "Split character for old and new filename pairs" + description: "Split character for old and new filename pairs." required: false default: "," old_new_files_separator: - description: "Split character for multiple old and new filename pairs" + description: "Split character for multiple old and new filename pairs." required: false default: " " files_from_source_file: - description: "Source file(s) to populate the files input" + description: "Source file(s) used to populate the `files` input." required: false default: "" files: - description: "Check for changes using only this list of files (Defaults to the entire repo)" + description: "File and directory patterns to detect changes using only these list of file(s) (Defaults to the entire repo) **NOTE:** Multiline file/directory patterns should not include qoutes." required: false default: "" files_separator: - description: "Separator used to split the files input" + description: "Separator used to split the `files` input" default: "\n" required: false files_ignore: - description: "Ignore changes to this list of files" + description: "Ignore changes to these file(s) **NOTE:** Multiline file/directory patterns should not include qoutes." required: false default: "" files_ignore_separator: - description: "Separator used to split the files-ignore input" + description: "Separator used to split the `files-ignore` input" default: "\n" required: false files_ignore_from_source_file: - description: "Source file(s) to populate the files-ignore input" + description: "Source file(s) used to populate the `files_ignore` input" required: false default: "" sha: - description: "Specify a current commit SHA used for comparing changes" + description: "Specify a different commit SHA used for comparing changes" required: true default: ${{ github.sha }} base_sha: - description: "Specify a base commit SHA on used for comparing changes" + description: "Specify a different base commit SHA used for comparing changes" required: false since: - description: "Get changed files for commits whose timestamp is older than the given time" + description: "Get changed files for commits whose timestamp is older than the given time." required: false default: "" until: - description: "Get changed files for commits whose timestamp is earlier than the given time" + description: "Get changed files for commits whose timestamp is earlier than the given time." required: false default: "" path: - description: "Specify a relative path under $GITHUB_WORKSPACE to locate the repository" + description: "Specify a relative path under `$GITHUB_WORKSPACE` to locate the repository." required: false default: "." quotepath: - description: "Output filenames completely verbatim by setting this to false" + description: "Use non ascii characters to match files and output the filenames completely verbatim by setting this to `false`" default: "true" required: false diff_relative: - description: "Exclude changes outside the current directory and show pathnames relative to it" + description: "Exclude changes outside the current directory and show pathnames relative to it. **NOTE:** This requires you to specify the top level directory via the `path` input." required: false dir_names: default: "false" - description: "Output the absolute path to the changed directories instead of the filenames" + description: "Output unique changed directories instead of filenames. **NOTE:** This returns `.` for changed files located in the root of the project." required: false json: - description: "Output changed files in JSON format which can be used for matrix jobs" + description: "Output list of changed files in a JSON formatted string which can be used for matrix jobs." required: false default: "false" max_fetch_depth: @@ -84,67 +84,67 @@ inputs: outputs: added_files: - description: List of added files. + description: "Returns only files that are Added (A)." value: ${{ steps.changed-files.outputs.added_files }} copied_files: - description: List of copied files. + description: "Returns only files that are Copied (C)." value: ${{ steps.changed-files.outputs.copied_files }} deleted_files: - description: List of deleted files. + description: "Returns only files that are Deleted (D)." value: ${{ steps.changed-files.outputs.deleted_files }} modified_files: - description: List of modified files. + description: "Returns only files that are Modified (M)." value: ${{ steps.changed-files.outputs.modified_files }} renamed_files: - description: List of renamed files. + description: "Returns only files that are Renamed (R)." value: ${{ steps.changed-files.outputs.renamed_files }} all_old_new_renamed_files: - description: List of all old and new names of renamed files. + description: "Returns only files that are Renamed and list their old and new names. **NOTE:** This requires setting `include_all_old_new_renamed_files` to `true` (R)" value: ${{ steps.changed-files.outputs.all_old_new_renamed_files }} type_changed_files: - description: List of files that had type changes. + description: "Returns only files that have their file type changed (T)." value: ${{ steps.changed-files.outputs.type_changed_files }} unmerged_files: - description: List of unmerged files. + description: "Returns only files that are Unmerged (U)." value: ${{ steps.changed-files.outputs.unmerged_files }} unknown_files: - description: List of unknown files. + description: "Returns only files that are Unknown (X)." value: ${{ steps.changed-files.outputs.unknown_files }} all_changed_and_modified_files: - description: List of all changed files. + description: "Returns all changed and modified files i.e. *a combination of (ACMRDTUX)*" value: ${{ steps.changed-files.outputs.all_changed_and_modified_files }} all_changed_files: - description: List of all copied, modified, and added files. + description: "Returns all changed files i.e. *a combination of all added, copied, modified and renamed files (ACMR)*" value: ${{ steps.changed-files.outputs.all_changed_files }} any_changed: - description: Return true only when any files provided using the files input have changed. + description: "Returns `true` when any of the filenames provided using the `files` input has changed. If no `files` have been specified,an empty string `''` is returned. i.e. *using a combination of all added, copied, modified and renamed files (ACMR)*." value: ${{ steps.changed-files.outputs.any_changed }} only_changed: - description: Return true when all files provided using the files input have changed. + description: "Returns `true` when only files provided using the `files` input has changed. If no `files` have been specified,an empty string `''` is returned. i.e. *using a combination of all added, copied, modified and renamed files (ACMR)*." value: ${{ steps.changed-files.outputs.only_changed }} other_changed_files: - description: Return list of changed files not listed in the files input. + description: "Returns all other changed files not listed in the files input i.e. *using a combination of all added, copied, modified and renamed files (ACMR)*." value: ${{ steps.changed-files.outputs.other_changed_files }} all_modified_files: - description: List of all copied, modified, added and deleted files. + description: "Returns all changed files i.e. *a combination of all added, copied, modified, renamed and deleted files (ACMRD)*." value: ${{ steps.changed-files.outputs.all_modified_files }} any_modified: - description: Return true only when any files provided using the files input have been modified. + description: "Returns `true` when any of the filenames provided using the `files` input has been modified. If no `files` have been specified,an empty string `''` is returned. i.e. *using a combination of all added, copied, modified, renamed, and deleted files (ACMRD)*." value: ${{ steps.changed-files.outputs.any_modified }} only_modified: - description: Return true when all files provided using the files input have been modified. + description: "Returns `true` when only files provided using the `files` input has been modified. If no `files` have been specified,an empty string `''` is returned.(ACMRD)." value: ${{ steps.changed-files.outputs.only_modified }} other_modified_files: - description: Return list of modified files not listed in the files input. + description: "Returns all other modified files not listed in the files input i.e. *a combination of all added, copied, modified, and deleted files (ACMRD)*" value: ${{ steps.changed-files.outputs.other_modified_files }} any_deleted: - description: Return true only when any files provided using the files input have been deleted. + description: "Returns `true` when any of the filenames provided using the `files` input has been deleted. If no `files` have been specified,an empty string `''` is returned. (D)" value: ${{ steps.changed-files.outputs.any_deleted }} only_deleted: - description: Return true when all files provided using the files input have been deleted. + description: "Returns `true` when only files provided using the `files` input has been deleted. If no `files` have been specified,an empty string `''` is returned. (D)" value: ${{ steps.changed-files.outputs.only_deleted }} other_deleted_files: - description: Return list of deleted files not listed in the files input. + description: "Returns all other deleted files not listed in the files input i.e. *a combination of all deleted files (D)*" value: ${{ steps.changed-files.outputs.other_deleted_files }} runs: