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.
• 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: Primarily for project-id.
2. Config file (~/.redmine-tree.json): For host and token.
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 and token for your Redmine instance.

Example ~/.redmine-tree.json:

{
  "host": "https://your-redmine.example.com",
  "token": "your_redmine_api_key"
}

• host: The base URL of your Redmine instance.
• token: Your Redmine API access key.

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.

Project ID

The project-id is provided as a command-line argument. If no project-id is provided, the application will list all available projects.

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.

Usage

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

• To list all projects:

  # Using the installed executable (Linux/macOS)
  redmine-tree
  
  # From the build directory (Linux/macOS)
  ./build/redmine-tree
  
  # On Windows (from build directory)
  .\build\redmine-tree.exe
  

• To show the issue tree for a specific project:

  # Using the installed executable (Linux/macOS)
  redmine-tree my-project-id
  
  # From the build directory (Linux/macOS)
  ./build/redmine-tree my-project-id
  
  # On Windows (from build directory)
  .\build\redmine-tree.exe my-project-id
  

Cleaning

To remove the build/ directory and compiled executables:

make clean