Skip to content

GitEHR Developer Guide

This document explains how to build and manually test the current GitEHR CLI features.

Prerequisites

  • cargo available on your PATH

Building the CLI

From the CLI project root:

cd gitehr
cargo build

This compiles the gitehr binary in debug mode under target/debug/gitehr.

To build and install the release binary into ~/.cargo/bin so it is available globally:

cd gitehr
cargo install --path .

After install, you should be able to run:

gitehr --help

Repository Layout (CLI)

Relevant paths inside the CLI repo:

  • gitehr/ – Rust CLI project root
  • gitehr/gitehr-folder-structure/ – template copied by gitehr init
  • README.md – root repository README template
  • journal/ – journal directory template
  • state/ – clinical state directory template
  • imaging/ – imaging directory template
  • gitehr/src/commands/ – Rust implementations of CLI commands
  • init.rs – repository initialization logic (creates folders + genesis entry)
  • journal.rs – journal entry creation and chaining

From the CLI crate root (where Cargo.toml lives):

cd gitehr
cargo set-version --bump patch   # or: minor, major

cargo build      # or: cargo install --path .

  1. Make and test your changes (see sections above).
  2. Decide the appropriate semver level (patch/minor/major).
  3. From the CLI crate root:
cargo set-version --bump patch   # or minor/major
  1. Commit your changes, including Cargo.toml and any code.
  2. If using git tags, create and push them as appropriate, for example:
git tag vX.Y.Z
git push --tags

This keeps the Cargo version, git history, and published binaries aligned. - Creates - .gitehr/ - journal/ - state/ Use the built-in Cargo command instead: - imaging/ - README.md (root) - Creates a genesis journal entry in journal/ with: - A filename of the form YYYYMMDDTHHMMSSZ-<UUID>.md - YAML front matter including: - parent_hash: a random 32‑byte seed hashed with SHA‑256 - timestamp: current UTC time - Body text: Genesis entry for GitEHR repository

How to manually test:

  1. Choose or create a directory to act as a test EHR repo (outside the CLI repo is recommended):
cd /home/marcus/code/gitehr
rm -rf test-ehr
mkdir test-ehr
cd test-ehr
  1. Run init:
gitehr init
  1. Verify structure:
ls -la
ls -la journal state imaging .gitehr

You should see:

  • .gitehr/ directory
  • journal/, state/, imaging/ directories

  • README.md in the root copied from the template

  • Inspect the genesis journal entry:

ls journal
cat journal/*.md

Confirm:

  • Exactly one .md file exists (if you only ran init once)
  • YAML front matter contains parent_hash (not null) and timestamp
  • The body text matches the genesis description

2. gitehr add

Adds a new clinical entry to the journal/ directory of the current GitEHR repository.

What it does:

  • Requires that a journal/ directory already exists (normally created by gitehr init)
  • Reads the latest journal entry (by filename sort order) and computes its SHA‑256 hash
  • Creates a new journal entry file with:
  • A filename of the form YYYYMMDDTHHMMSSZ-<UUID>.md
  • YAML front matter including:
    • parent_hash: the hash of the latest existing entry
    • timestamp: current UTC time
  • Body text: the string you passed on the command line

How to manually test:

  1. From an initialized test repo (see gitehr init steps above):
cd /home/marcus/code/gitehr/test-ehr
gitehr add "First clinical entry"
  1. List the journal files:
ls journal

You should see at least two .md files now: one genesis entry and one for the new entry.

  1. Inspect the files:
cat journal/*.md

Confirm for the newest entry:

  • parent_hash is different from the genesis seed hash
  • parent_hash matches the SHA‑256 hash of the full contents of the previous entry file

  • The body contains First clinical entry (or your provided text)

  • (Optional) Manually verify the hash:

# Replace GENESIS_FILE with the actual filename
GENESIS_FILE=$(ls journal | sort | head -n1)
NEWEST_FILE=$(ls journal | sort | tail -n1)

# Compute hash of the genesis file
HASH=$(sha256sum "journal/$GENESIS_FILE" | awk '{print $1}')
echo "Genesis hash: $HASH"

# Show parent_hash from newest file
grep parent_hash "journal/$NEWEST_FILE"

The parent_hash in the newest file should match HASH.

Typical Local Dev Workflow

From the CLI repo root (gitehr/):

  1. Edit code:
cd gitehr
# edit src/*
  1. Build + run tests (none yet, but build verifies compilation):
cargo build
  1. Install and run against a throwaway test repo:
cargo install --path .

cd ..
rm -rf test-ehr
mkdir test-ehr
cd test-ehr

gitehr init
gitehr add "Test entry"
  1. Inspect generated files and adjust implementation as needed.

Versioning

GitEHR follows semantic versioning (MAJOR.MINOR.PATCH) and keeps the canonical version in gitehr/Cargo.toml under the [package] section.

Version bump policy

  • PATCH (x.y.z -> x.y.(z+1))
  • Backwards-compatible bug fixes or internal changes that don’t affect the public CLI surface or on‑disk data layout.
  • MINOR (x.y.z -> x.(y+1).0)
  • Backwards-compatible feature additions.
  • New commands, new flags, or new fields that older clients can safely ignore.
  • MAJOR (x.y.z -> (x+1).0.0)
  • Breaking changes to the CLI interface or on-disk format.
  • Anything that may invalidate existing EHR repos or tools built on top of GitEHR.

Bumping the version

Use the helper script in the repo root (parent of gitehr/):

cd /home/marcus/code/gitehr
./scripts/bump_version.sh patch   # or: minor, major

What the script does:

  1. Reads the current version from gitehr/Cargo.toml.
  2. Computes the new version based on the argument (major / minor / patch).
  3. Rewrites the version = "…" field under [package] in gitehr/Cargo.toml.
  4. If the directory is a git repo, creates a tag vNEW_VERSION on the current commit.

After bumping, rebuild/install as usual:

cd gitehr
cargo build      # or: cargo install --path .
  1. Make and test your changes (see sections above).
  2. Decide the appropriate semver level (patch/minor/major).

  3. From the repo root:

    ./scripts/bump_version.sh patch   # or minor/major

  4. Commit your changes, including gitehr/Cargo.toml and any code.

  5. If using git tags, push them:

    git push --tags

This keeps the Cargo version, git history, and published binaries aligned.

Notes / Future Hooks

  • The current CLI is intentionally small and focused on:
  • Repository initialization
  • Journal entry creation and chaining
  • Planned future commands (not yet implemented):
  • gitehr status
  • gitehr encrypt / gitehr decrypt
  • gitehr transport / gitehr extract
  • GUI (gitehr-gui/) will eventually sit alongside this CLI and talk to the same on-disk structure.

Keep this document updated as new commands and behaviours are added.