Full presentation

What it is, what it isn't

This tool is a command line interface to help you install and configure a hook to your git repository. This hook will automatically create issues or comment existing ones when it finds a new "TODO" in committed files.

It's not a GitHub issue manager, you can take a look at gh or ghi for this.

Why it exists

While coding I often encounter little details that could be improved, little issues that could be fixed but do not match my current goal and are not urgent… In those cases I generally end up adding a little TODO we should definitely improve this. I don't get disturbed and let the little things aside, focusing on the main goal.

But those TODOs are then usually lost in code, and take a thousand years to be fixed, never raise any discussion. It's hardly better than doing nothing at all. That's why I thought about a tool that would automatically create an issue for each TODO.

Who can use it

Any Github user can use it:

• it only requires the permission to create issue on repository
• it's language agnostic, just detecting word TODO, in comment or anywhere else

When you can use it

• On any existing repository you run github-todos init to install hook, a bunch of github-todos config calls to tweak behavior, it will then run when you push your contributions
• You can also use it on an existing codebase, to convert those already lost TODOs into issues. This is a very specific usage that you should first simulate:

# Simulation
DRY_RUN=1 github-todos _hook --remote origin --range firstCommit..lastCommit

# Looks OK, let's run the real thing
github-todos _hook --remote origin --range firstCommit..lastCommit

How it works under the hood

The hook itself

• TODOs detection is very simple stupid: any new line matching "TODO …" causes an issue to be created or commented
  • If the lines matches "TODO # …" then it will comment the corresponding issue
  • If multiple TODOs with the same text are found, only one issue will be open
  • Optionally it will modify any "TODO …" into "TODO # …" after creating or commenting issue, all modifications being isolated in a
    • stash if workspace is dirty
    • modify source files
    • add, commit
    • stash pop if necessary
• The hook is triggered on pre-push
  • As it's an operation requiring network (Github API) it should be linked to push
  • It sounds dumb to create issue for unpublished code

Issue injection

1. git stash save --include-untracked if workspace is dirty
2. modify source files: TODO … → TODO #X …
3. git add .
4. git commit -m "[Github-Todos] Inject issue numbers"
5. git stash pop --index if stashed on step 1
6. Ready to let the push go

The configuration layer

Configuration is store in .github-todos file, using INI format.

• $HOME/.github-todos contains global configuration, overridden by…
• <YOUR-REPO>/.github-todos which contains local (repository-wide) configuration

Installing the hook

• If no pre-push hook exists it creates the file with the simple github-todos _hook command
• If a pre-push hook exists, Github-Todos will grep it for the expected command
  • If found, do nothing
  • If not found, add it on top

As soon as you don't manually edit the Github-Todos hook command in pre-push file, github-todos init can install/uninstall hook painlessly.

If you have any doubt, you should manually insert the command (read doc/hooks/command.txt to get it).