redmine-tree/README.md

Redmine Issue Tree Generator

This Go application fetches issues from a Redmine instance for a specified project and displays them in a tree-like structure, reflecting their parent-child relationships.

Features

• Fetches issues from Redmine API for a given project and displays the project name.
• Organizes issues into a hierarchical tree based on parent-child relationships.
• Displays issue ID, subject, and status.
• Filter issues by status (include or exclude specific statuses).
• Lists all available Redmine projects (ID and Name) if no project-id is provided.
• Supports configuration via environment variables, a .env file, or a ~/.redmine-tree.json configuration file.

Setup

1. Install Go dependencies:

   go mod tidy
   

Configuration

The application retrieves configuration in the following order of precedence:

1. Command-line arguments: Flags like -status and -exclude-status and the project-id.
2. Config file (~/.redmine-tree.json): For host, token, and default status filters.
3. Environment Variables: REDMINE_URL and REDMINE_TOKEN (these will override values from the config file if set).

Config File (~/.redmine-tree.json)

You can create a JSON configuration file named .redmine-tree.json in your home directory (~). This file can contain the host, token, and default filtering preferences.

Example ~/.redmine-tree.json:

{
  "host": "https://your-redmine.example.com",
  "token": "your_redmine_api_key",
  "include_statuses": ["In Progress", "Feedback"],
  "exclude_statuses": ["Done", "Closed"]
}

• host: The base URL of your Redmine instance.
• token: Your Redmine API access key.
• include_statuses: Optional list of status names or IDs to include by default.
• exclude_statuses: Optional list of status names or IDs to exclude by default.

Environment Variables

You can set REDMINE_URL and REDMINE_TOKEN as environment variables. These values will override any corresponding settings found in ~/.redmine-tree.json. For convenience, you can create a file named .env in the root directory of the project. You can use env-example as a template:

cp env-example .env

Edit the .env file with your Redmine instance details:

REDMINE_URL=https://your-redmine.example.com
REDMINE_TOKEN=your_redmine_api_key

• REDMINE_URL: The base URL of your Redmine instance (e.g., https://redmine.example.com).
• REDMINE_TOKEN: Your Redmine API access key.

Usage

After building (and optionally installing), you can run the application.

IMPORTANT: Flags must come BEFORE the project ID.

Filtering by Status

You can filter issues by their status name or ID using comma-separated values.

• -status: Only include issues with these statuses.
• -exclude-status: Exclude issues with these statuses.

Examples:

# Exclude "Done" and "Closed" issues
redmine-tree -exclude-status="Done,Closed" my-project-id

# Only show "New" and "In Progress" issues
redmine-tree -status="New,In Progress" my-project-id

# Mix and match (IDs work too)
redmine-tree -status="In Progress" -exclude-status="5" my-project-id

Basic Commands

• To list all projects:

  redmine-tree
  

• To show the issue tree for a specific project:

  redmine-tree my-project-id
  

Obtaining your Redmine API Token

To get your Redmine API access key:

1. Log in to your Redmine instance.
2. Click on "My Account" in the top right corner.
3. On the "My Account" page, you will find an "API access key" section.
4. Copy the key displayed there. If no key is present, you might need to enable "Enable REST API" in Redmine's administration settings (Administration -> Settings -> Authentication).

Building and Installing

Use the provided Makefile to build and install the application.

Build

To build the executable:

make build

This will create an executable named redmine-tree (or redmine-tree.exe on Windows) in the build/ directory.

Install

To install the executable:

make install

• On Linux/macOS: This will install the redmine-tree executable to ~/.local/bin/. Ensure ~/.local/bin/ is in your system's PATH to run the command directly from any directory.
• On Windows: The executable will be built to build/redmine-tree.exe. The install command will inform you of its location and advise you to manually add its directory to your system's PATH if you wish to run it from any location.

Cleaning

To remove the build/ directory and compiled executables:

make clean