Working with old issues

GrainyHead provides two commands to work with “old” issues – issues that have not been updated (no comments or addition/removal of an issue label) for a given amount of time (by default, 365 days).

Listing old issues

The issues command list old issues in the repository. It produces a Markdown-formatted table giving, for each issue, its title, the user who authored it and whether that user is a known contributor to the repository, and the user(s) to which the issue has been assigned, if any.

Use the --older-than option to change the duration after which an issue is consider to be “old“. This option accepts:

  • a plain date, written as YYYY-MM-DD or YYYY-MM;

  • a number of days, written as Xd or simply as X;

  • a number of weeks, written as Xw;

  • a number of months, written as Xm;

  • a number of years, written as Xy;

  • the value now, representing the current date (would consider all issues as old).

With the --team NAME option, the command will indicate for each issue whether the author is a member of the team NAME, instead of whether they are a “known contributor”. This requires that the user account associated with the access token is a member of the organisation the team belongs to and that the token has the read:org permission.

The following example will list issues that have not been updated in the past 6 months and indicate whether their authors belong to the elite team:

$ grainyhead issues --older-than 6m --team elite

Closing old issues

The close command will automatically close all issues that are considered “old” (the same issues that are listed by the issues command above). A label autoclosed-unfixed (which will be created if it didn’t already exist in the repository) will be added to those issues.

As for the issues command, use the --older-than option to change the threshold duration after which an issue is considered “old”.

If the --comment option is used on the command line, or if the configuration file contains a close.comment option, a comment will be appended to each issue before they are closed.

Use the --limit N option to only close the N oldest issues.

The issues that would be closed by the command are printed on the terminal and an explicit confirmation is asked before the command proceeds with the actual closing process. If the --dry-run option is used, the command only lists the issues to be closed without going further.

The following example will close the 30 oldest issues that have not been updated in the past 3 years:

$ grainyhead close --older-than 3y --limit 30 \
  --comment "This issue has been closed automatically."