Initial project commit
This commit is contained in:
@@ -0,0 +1,172 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user