initial commit

README.md

@@ -0,0 +1,137 @@
+# 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:**
+    ```bash
+    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`:
+
+```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:
+
+```bash
+cp env-example .env
+```
+
+Edit the `.env` file with your Redmine instance details:
+
+```ini
+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:
+
+```bash
+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:
+
+```bash
+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:**
+
+    ```bash
+    # 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:**
+
+    ```bash
+    # 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:
+
+```bash
+make clean
+```