Snitch is a terminal-based utility that automates the creation of interactive and informative reports in both markdown and text for the reporting of GitHub repository issues.
To install Snitch with NPM, please run the following command in your terminal:
> npm i -g 4awpawz/snitch| Report Name | Description | Example |
|---|---|---|
| assignee | a list of issues by assignee | > snitch --name=assignee > snitch-report.md |
| label | a list of issues by label | > snitch --name=label > snitch-report.md |
| list | a list of issues | > snitch --name=list > snitch-report.md |
| milestone | a list of issues by milestone | > snitch --name=milestone > snitch-report.md |
| milestone-label | a list of issues by milestone and label | > snitch --name=milestone-label > snitch-report.md |
| Option | Description | Default (if omitted) | Example |
|---|---|---|---|
| --as-text (v3.0.0) | output report as plain text | output report as markdown | --as-text |
| --blank-lines (v3.0.0) | seperate issues with a blank line | no seperating blank line | --blank-lines |
| --debug | run in debug mode, see below for details | run in normal mode | --debug |
| --heading=[report heading] | the heading for the report | repository name | --heading=CHANGELOG |
| --max-issues=integer | maximum number of issues to report on | 10000 | --max-issues=100000 |
| --name=[list | milestone | milestone-label | label | assignee] | name of report to generate | list | --name=milestone-label |
| --no-heading (v3.0.0) | omit heading | include heading | --no-heading |
| --non-interactive | for markdown reports only, generate non interactive issues | generate interactive issues | --non-interactive |
| --no-attribution | attribution is jnot appended to the report | attribution is appended to the report | --no-attribution |
| --repo=[path to repository] | path to Github repository | the GitHub repository associated with the current project determined by git remote origin | --repo=4awpawz/snitch |
| --state=[all | open | closed] | limit reporting to issues with this state | all | --state=closed |
Use redirection (i.e., >) to save output to a file:
> snitch --name=list > list.mdYou can run Snitch in debug mode to expose the dynamically generated configuration data that would be used during the processing of the payload returned from GitHub's CLI utility as well as the command line that would be used to invoke GitHub CLI itself. This information would be useful when submitting an issue or for your own problem resolution.
To invoke debug mode, append --debug to the command line that you would use to generate your desired report, such as the list report in the command below:
> snitch --name=list --debug The output from running Snitch in debug mode would look similar to the following:
debug config: {
reportName: 'list',
repo: 'https://github.com/4awpawz/snitch',
state: 'all',
maxIssues: 10000,
nonInteractive: false,
noHeading: false,
heading: '4awpawz/snitch',
debug: true,
noAttribution: false,
asText: false,
blankLines: false
}
debug gh command: gh issue list -L 10000 --state all --json 'number,title,labels,milestone,state,assignees,url' -R https://github.com/4awpawz/snitchYou can also run the debug gh command to examine the JSON payload returned by GitHub's gh utility:
> gh issue list -L 10000 --state all --json 'number,title,labels,milestone,state,assignees,url' -R https://github.com/4awpawz/snitchWhen generating a report other than the list report you might see a warning message like the one below. It is informing you that some issues were excluded from the report because they didn't meet the report's requirements. For example, if you generate a milestone report and there are issues that haven't been assigned a milestone then those issues will be excluded from the report.
> snitch --name=list --state=closed --heading=CHANGELOG
Have an idea for a report format that is not yet supported? Then by all means please submit a request and provide a detailed description of the report you are seeking.
MIT
Please 👀 watch and leave us a 🌟 star :)