Skip to content

Commands ‐ todoon

Jump to bottom
Trenton Young edited this page Jun 18, 2024 · 9 revisions

todoon

Usage

 Usage: todo_check.py todoon [OPTIONS] [FILES]...                               
                                                                                
 Checks files for occurrences of TODO or FIXME and reports them for use with    
 automation or other development operations                                     
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│   files      [FILES]...  If specified, only these [FILES] will be scanned    │
│                          for TODOs and FIXMEs. Otherwise, all files in the   │
│                          current working directory except for those          │
│                          specified in .todo-ignore will be scanned           │
│                          [default: None]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --print                   -p  --issue  -i    Whether to print the discovered │
│                                              TODOs and FIXMEs to stderr or   │
│                                              to try generating GitHub issues │
│                                              [default: print]                │
│ --silent                  -s                 (No fail) If specified, todoon  │
│                                              will not exit with an error     │
│                                              code even when TODOs and/or     │
│                                              FIXMEs are detected             │
│ --closed-duplicates-fail  -c                 If specified, todoon will exit  │
│                                              with error code if duplicate    │
│                                              GitHub issues are found in a    │
│                                              'closed' state, will do so even │
│                                              if --silent/-s is specified     │
│ --github-env                                 If specified, todoon will push  │
│                                              environment variables to the    │
│                                              special $GITHUB_ENV file. This  │
│                                              allows the variables to persist │
│                                              across steps in a workflow.     │
│ --force                   -f                 (NOT RECOMMENDED) If specified, │
│                                              no .todo-ignore file will be    │
│                                              used                            │
│ --verbose                 -V                 If specified, todoon will not   │
│                                              to print lengthy or numerous    │
│                                              messages (like each encoding    │
│                                              failure)                        │
│ --quiet                   -q                 If specified, todoon will only  │
│                                              print the summary               │
│ --very-quiet              -Q                 If specified, todoon will not   │
│                                              print anything at all           │
│ --progress-bar            -P                 If specified, todoon will       │
│                                              display a progress bar while    │
│                                              scanning files. NOTE: This adds │
│                                              a small amount of overhead      │
│                                              (will take a little longer)     │
│ --version                 -v                 Show the application version    │
│                                              and exit.                       │
│ --help                                       Show this message and exit.     │
╰──────────────────────────────────────────────────────────────────────────────╯

Arguments

[FILES] : This optional argument allows you to specify which files todoon should scan. When left blank, todoon will scan every file in the working directory that is not filtered out by the .todo-ignore

Feedback

Summary

todoon will summarize the run in the console when it completes. As an example, this output comes from a call to todoon -sf which forced a scan of this entire repository:

##########################
# Summary
# (PRINT MODE)
# 375 TODO | 23 FIXME
# 71 Files skipped due to unsupported encodings
# 186 Files scanned
##########################

  * INFO: New issues detected, but todoon ran in --silent mode

Note

Consider this line of the output:

# 71 Files skipped due to unsupported encodings

If a file discovered by todoon is not of a supported encoding [see SUPPORTED_ENCODINGS_TODO_CHECK for most up-to-date list] it will be skipped.

Environment

During and after the course of a run, todoon will set/update a number of environment variables:

  • $TODOON_STATUS
    • starting
    • parsing-todo-ignore (if [FILES] is not specified, default behavior)
    • collecting-targets (if no [FILES] specified)
    • collecting-issues (if -i or --issue is specified)
    • scanning-files
    • finished
  • $TODOON_PROGRESS
    • starting at status scanning-files, this variable is updated to a percentage represented as a string (e.g. '18.7') which reflects the number of targets scanned of all targets found
  • $TODOON_FILES_SCANNED
  • $TODOON_TODOS_FOUND
  • $TODOON_FIXMES_FOUND
  • $TODOON_ENCODING_ERRORS
  • $TODOON_ISSUES_GENERATED
  • $TODOON_DUPLICATE_ISSUES_AVOIDED
  • $TODOON_DUPLICATE_CLOSED_ISSUES

Important

GitHub Actions integration:

Make note of the --github-env option, in order for environment variables to persist across steps in a job this option must be enabled!

When enabled, environment variables should be accessed with the "${{ env.TODOON_DUPLICATE_CLOSED_ISSUES }}" syntax, see this workflow for a good example of how this works see this workflow that shows a persistent environment variable across jobs being used for more granular control over closed issues.

Under the hood, the GitHub Actions environment uses a special file ($GITHUB_ENV) that stores these variables. When you enable the --github-env flag, todoon will write to that file in addition to exporting the env variables. This has strange behaviors outside of the GitHub Actions environment, so you should only need it in your workflows.

Issues

Issues are generated up to a limit (see Environment Variables) and contain the line which contains the TODO or FIXME and up to $MAXIMUM_ISSUES_GENERATED of the preceding and following lines. See the examples in the README for a good representation of how these look.

Issue generation is best supported from GitHub actions, the YAML included in this repository generates the necessary credentials and keeps them safe for you, so it's the most recommended option. However, if you wish to run this elsewhere, you must supply valid values to each of the following environment variables:

  • GITHUB_REF_NAME
  • GITHUB_REPOSITORY
  • GITHUB_TRIGGERING_ACTOR

Examples

Find ALL issues in the current working directory (including any hidden folders/files) and exit non-zero if any are found

todoon --force

Show the issues the files "a.txt", "b.txt", and all the files that are under the directory "c/" without failing

todoon --silent a.txt b.txt c/

Generate all the issues found in the project that haven't already been generated, but exit with an error if an issue is found to already be closed (assumes issues environment is set up correctly and a .todo-ignore is in place)

gh auth login 
todoon -ics
Clone this wiki locally