# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

`hebcal` is a command-line Jewish calendar program (a perpetual Hebrew calendar).
This repository is a **thin CLI wrapper**: it parses arguments, then delegates
nearly all calendar logic to the `github.com/hebcal/hebcal-go` library. There is
very little domain logic here — if you're looking for how holidays, sedrot,
zmanim, candle-lighting, or Hebrew-date conversion are actually computed, the
answer is in the `hebcal-go`, `hdate`, `greg`, `learning`, and `locales`
dependencies, not in this repo.

## Build, test, run

```sh
make            # build the `hebcal` binary and the `hebcal.1` man page
make test       # build, then `go test ./...` (alias: `make check`)
make clean      # remove binary, man page, and generated dcity.go
make install    # install to $PREFIX (default /usr/local)
go test -run TestName ./...   # run a single test
```

`make` (not bare `go build`) is the correct build entry point because two source
files are **generated** and `go build` alone won't produce them:

- `dcity.go` — generated by the Makefile; defines `defaultCity` (default `"New York"`,
  overridable via `make DEFAULT_CITY=...`). It's in `.gitignore`.
- `hebcal.1` — generated from `hebcal.1.in` by substituting `@VERSION@` with the
  version parsed out of `version.go`.

CI (`.github/workflows/go.yml`) runs `make all` then `make test` on Go 1.18.

## Code layout

- `main.go` — the whole program. `handleArgs()` builds a `hebcal.CalOptions`
  struct from getopt flags; `main()` resolves the date range, calls the library
  to produce events, and prints them. Most CLI flags map directly onto fields of
  `hebcal.CalOptions`, so adding a flag that the library already supports is
  usually just one `opt.FlagLong(&calOptions.X, ...)` line.
- `user.go` — parsers for the `-I` user-events file and `-Y` yahrzeit file.
- `version.go` — single source of truth for the version string. Drives both the
  man page version and the `hebcal info` / `--version` output.
- `gnu.go` — text for `hebcal copying` / `hebcal warranty` (GNU license).

## Conventions

- **Releases:** bump `Version` in `version.go` and add a matching section to the
  top of `NEWS.md`. Dependency upgrades (especially `hebcal-go` and `learning`)
  are typically the substance of a release — note the module versions in NEWS.md,
  as existing entries do.
- **Flag style:** flags use `pborman/getopt/v2`. Globals named `<thing>_sw`
  are package-level switches read by `main()`; prefer wiring new options straight
  into `calOptions` fields when the library exposes them.
- `README.md` is the authoritative source for user-facing option docs and is kept
  in sync with `hebcal.1.in`. `README_DE.md` is a German translation of it.
