git-issue

git-issue This is a minimalist decentralized issue management system based on Git, offering (optional) biderectional integration with GitHub and GitLab issue management. It has the following advantages over other systems. No backend, no dependencies: You can install and use git issue with a single shell command. There's no need for a server or a database back-end, and the corresponding problems and requirements for their administration. Decentralized asynchronous management: Anyone can add, comment, and edit issues without requiring online access to a centralized server. There's no need for online connectivity; you can pull and push issues when you're online. Transparent text file format: Issues are stored as simple text files, which you can view, edit, share, and backup with any tool you like. There's no risk of losing access to your issues because a server has failed. Git-based: Issues are changed and shared through Git. This provides git issue with a robust, efficient, portable, and widely available infrastructure. It allows you to reuse your Git credentials and infrastructure, allows the efficient merging of work, and also provides a solid audit trail regarding any changes. You can even use Git and command-line tools directly to make sophisticated changes to your issue database. Installation Administrator installation Clone the repo and run make install with appropriate privileges. Personal installation Clone the repo and register a git alias to the git-issue.sh script: git config --global alias.issue '!'"${REPO_PATH}/git-issue.sh" If you are using a bash shell, you can also register the autocompletion by adding the following to your .bashrc. source ${REPO_PATH}/gi-completion.sh Backward compatibility with the gi command For backward compatibility you can also use the original gi command, by copying gi.sh to someplace in your path. In this case you must register the git alias to use the auto completion feature. If you have administrative access you can install it with sudo install gi.sh /usr/local/bin/gi. For your personal use, assuming that the directory ~/bin exists and is in your path, you can install it with install gi.sh ~/bin/gi. You can even put gi in your project's current directory and run it from there. Portability and testing The git-issue.sh script has been tested on: Archlinux (20220101) Debian GNU/Linux FreeBSD macOS Cygwin. If you're running git issue on another system, run the test.sh script to verify its operation, and (please) update this file. Requirements git-issue requires the jq and curl utilities. OS X users might also need GNU date, obtained by installing homebrew package coreutils. For running the tests shellcheck is also required. Use You use git issue with the following sub-commands. Start an issue repository git issue clone: Clone the specified remote repository. git issue init: Create a new issues repository in the current directory. The -e option uses an existing Git project repository. Work with an issue git issue new: Create a new open issue (with optional -s summary and -c "provider user repo" for github/gitlab export). git issue show: Show specified issue (and its comments with -c). git issue comment: Add an issue comment. git issue edit: Edit the specified issue's (or comment's with -c) description git issue tag: Add (or remove with -r) a tag. git issue milestone: Specify (or remove with -r) the issue's milestone. git issue weight: Specify (or remove with -r) the issue's weight. The weight is a positive integer that serves as a measure of importance. git issue duedate: Specify (or remove with -r) the issue's due date. The command accepts all formats supported by the date utility. git issue timeestimate: Specify (or remove with -r) a time estimate for this issue. Time estimates can be given in a format accepted by date, however bear in mind that it represents a time interval, not a date. git issue timespent: Specify (or remove with -r) the time spent working on an issue so far. Follows the same format outlined above. If the -a option is given, the time interval will be added together with the existing one. git issue assign: Assign (or remove -r) an issue to a person. The person is specified with his/her email address. The form @name or name@ can be used as a shortcut, provided it uniquely identifies an existing assignee or committer. Note that if you plan to export the issue to a GitHub/GitLab repository, the assignee may be rejected if it doesn't correspond to a valid username, or if you don't have the necessary permissions. git issue attach: Attach (or remove with -r) a file to an issue. git issue watcher: Add (or remove with -r) an issue watcher. git issue close: Remove the open tag, add the closed tag Show multiple issues git issue list: List open issues (or all with -a). An optional argument can show issues matching a tag or milestone. git issue list -l formatstring: This will list issues in the specified format, given as an argument to -l. The following escape sequences can be used: %n : newline %i : issue ID %c : creation date %d : due date %e : time estimate %s : time spent %w : weight %M : Milestone %A : Assignee(s) %T : Tags %D : Description(first line) If the format string is one of: (oneline, short or full) it will interpreted as the corresponding preset. Optionally, one of the above given with -o will order based on this field(reverse order with -r). Work with multiple issues git issue filter-apply command: Run command in every issue directory. The following environment variables will be set: GI_SHA : Sha of the current issue GI_IMPORTS : The imports directories for current issue(one on each line) GI_AUTHOR : Author of current issue GI_DATE : Creation date of current issue The command can read, add/remove or edit any of the issue's attributes. Some potentially useful scripts to be used with this command are in the scripts/ directory. Remember to inspect the results (e.g. gi git diff) and commit them with gi git comm