tr2gf/README.md

# tr2gf

Trade Republic transaction export converter for Ghostfolio.

`tr2gf.sh` converts a Trade Republic transaction export CSV into one Ghostfolio-compatible CSV file per selected ISIN or symbol. The script is POSIX-compliant, supports config-driven symbol and source mappings, optional CLI overrides, count-only runs and per-symbol export file naming based on the latest matching transaction date.

## Outline

- [Features](#features)
- [Repository layout](#repository-layout)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Examples](#examples)
- [Output format](#output-format)
- [Logging and troubleshooting](#logging-and-troubleshooting)
- [License](#license)
- [Authors](#authors)
- [Project Home](#project-home)

## Features

- Convert a Trade Republic CSV export into one Ghostfolio-compatible CSV file per matching symbol.
- Export `BUY` and `SELL` transactions and suppress matching `BUY_CANCELLED` records.
- Load runtime defaults and symbol/source mappings from a local `vars` file.
- Override symbol codes per selector on the command line via `-S` or `--symbol`.
- Run in count-only mode without writing export files.
- Keep the implementation portable with `#!/bin/sh` and standard Unix tools such as `awk`, `sed`, `grep` and `date`.

## Repository layout

```text
.
├── .gitignore
├── tr2gf.sh
├── vars.example
├── README.md
├── CHANGELOG.md
└── LICENSE
```

## Requirements

The script checks for the presence of `awk`, `sed`, `grep` and `date` at runtime and it expects a readable source CSV plus an output directory when not running in count-only mode.

## Installation

1. Clone the repository.
2. Copy `vars.example` to `vars`.
3. Adjust the runtime defaults and symbol mappings for the local environment.
4. Make `tr2gf.sh` executable.
5. Run a help or count-only command first to validate the setup.

```sh
git clone https://github.com/sduesterhaupt/tr2gf.git

cd tr2gf

cp vars.example vars
chmod 0750 tr2gf.sh
chmod 0640 vars

./tr2gf.sh help
```

The `tr2gf.sh` script is executable only for the repository owner, and the `vars` file is readable by owner and group to keep configuration and symbol mappings under tighter control.

## Configuration

The script initializes built-in defaults for the source file, output directory, account name, logging and default data sources, then loads overrides from a local `vars` file if present.

Supported configurable keys loaded from `vars` are:

- `TR2GF_SOURCE_FILE`
- `TR2GF_OUTPUT_DIR`
- `TR2GF_ACCOUNT_NAME`
- `TR2GF_YAHOO_SOURCE`
- `TR2GF_CRYPTO_SOURCE`
- `TR2GF_LOG_DIR`
- `TR2GF_LOG_FILE`
- `TR2GF_LOG_LEVEL`
- `TR2GF_BATCH`

Symbol mappings are read as colon-separated entries in the form `SYMBOL:CODE[:SOURCE]`. When no source is set, known crypto symbols default to the configured crypto data source and all other symbols default to the configured Yahoo source.

## Usage

General command form:

```sh
./tr2gf.sh [options] TARGET [target-options]
```

Global options implemented by the script:

- `-f FILE` define a specific Trade Republic source CSV.
- `-o DIR` define a specific export output directory.
- `-a NAME` define the account name written to the export CSV.
- `-c` count matching `BUY` and `SELL` transactions only.
- `-h`, `--help` show usage information.

Target modes implemented by the script:

- `ALL` export all matching `BUY` and `SELL` transactions found in the source CSV.
- `ISIN [target-opts]`  export transactions only for the specified selectors (e.g. ISINs and crypto tickers).

Target options implemented by the script (per selector):

- `-S SYMBOL`
- `--symbol SYMBOL`
- `--symbol=SYMBOL`

## Examples

Export all supported transactions into one file per symbol:

```sh
./tr2gf.sh ALL
```

Count transactions for selected selectors without writing files:

```sh
./tr2gf.sh -c IE00B4L5Y983 BTC
```

Export a selected symbol with a CLI override for the target code:

```sh
./tr2gf.sh IE00BK5BQT80 -S VWCE.DE
```

Write exports into a dedicated directory and set the Ghostfolio account label:

```sh
./tr2gf.sh -o ./exports -a "Trade Republic" ALL
```

## Output format

Each generated file starts with the Ghostfolio-compatible header `Date,Code,DataSource,Currency,Price,Quantity,Action,Fee,Account,Note` and the filename is prefixed with the latest matching transaction date in `YYMMDD` form.

The generated `Note` field uses the pattern `ISIN <symbol>`, while the `Action` column is mapped to `buy` or `sell` and fees are written as absolute numeric values.

## Logging and troubleshooting

The script contains a file-based logging system with severity levels from `0` to `5`, configurable via `TR2GF_LOG_LEVEL` and writes to `TR2GF_LOG_FILE` when enabled.

For troubleshooting, useful first checks are:

```sh
./tr2gf.sh help
./tr2gf.sh -c ALL
sed -n '1,5p' ./TradeRepublic_TransactionExport.csv
```

Adjust the filename in the example above if your Trade Republic export has a date prefix or a different name.

Typical failure points are a missing source CSV, a wrong output directory, absent required commands or mismatched CSV headers such as missing `date`, `type`, `symbol`, `name`, `shares`, `price`, `fee` or `currency` columns.

## License

This project is published under the MIT License. See `LICENSE` for details.

## Authors

- [Stephan Düsterhaupt](xmpp:me@jabber.stephanduesterhaupt.de)

## Project Home

Project Home: [https://dev.town-square.de/sduesterhaupt/tr2gf](https://dev.town-square.de/sduesterhaupt/tr2gf)