# `zfin contributions`

Show contributions, withdrawals, and lot-level changes between two
points in your portfolio's **git history**.

```
Usage: zfin contributions [opts]
```

`contributions` diffs two git revisions of your `portfolio*.srf` files
and attributes the share/lot changes to new money vs. market movement.
Every file matching the glob is read at both revisions and merged, so a
sold lot archived into a sibling `portfolio_closed.srf` is still seen.
Your portfolio must be under git with commits over time.

## Modes

| Invocation                  | Window                                                    |
|-----------------------------|-----------------------------------------------------------|
| (no flags), dirty tree      | `HEAD` vs. working copy                                   |
| (no flags), clean tree      | `HEAD~1` vs. `HEAD` (review the last commit)              |
| `--since <DATE>`            | commit at/before DATE vs. HEAD (or working copy if dirty) |
| `--since <D1> --until <D2>` | commit at/before D1 vs. commit at/before D2               |

`--until` alone is rejected (the window is ambiguous). Dates accept
`YYYY-MM-DD` or `1W`/`1M`/`1Q`/`1Y`.

## Options

| Flag                     | Effect                                                                              |
|--------------------------|-------------------------------------------------------------------------------------|
| `--since <DATE>`         | Earliest side (resolves to commit at/before).                                       |
| `--until <DATE>`         | Latest side (pair with `--since`).                                                  |
| `--commit-before <SPEC>` | Pin the before commit directly (same grammar as `--commit-after`, minus `working`). |
| `--commit-after <SPEC>`  | Pin the after commit: `YYYY-MM-DD`, relative, `HEAD`, `HEAD~N`, SHA, or `working`.  |

Pass at most one of `--since`/`--commit-before` (same axis), and at
most one of `--until`/`--commit-after`.

## Example

```bash
zfin contributions --since 1Y
```

## Internal movement

Money that was already inside an account is not a contribution -- it
just changed form. Two shapes are detected automatically, with no
bookkeeping on your part, and both report under **Internal purchases**
rather than counting toward the total:

- **Buying with cash already in the account.** The buy appears
  alongside the account's cash going down.
- **Reallocating -- selling one holding to buy another in the same
  account.** The sale's proceeds offset the repurchase.

A sale is valued at `close_price` when you record one (see
[`portfolio.srf`](../config/portfolio-srf.md)), which is what the sale
actually realized. If you delete the lot outright instead, there is no
`close_price` to read and the current market price stands in -- accurate
for a recent sale, less so for one made long before the end of the
window. The report labels which was used: `at close` or `at mark`.

Closing a position that has accumulated a lot per dividend
reinvestment retires many lots at once, so sales collapse to one line
per account and symbol, carrying the lot count and the total.

Proceeds still sitting in cash at the end of the window cannot have
funded anything, and are treated accordingly. On an account marked
`cash_is_contribution::true` they also cancel that account's cash
credit, since the sale is not new money even though cash arrived.

Movement **between** accounts is a different matter -- zfin cannot tell
it from a contribution, so declare it in
[`transaction_log.srf`](../config/transaction-log-srf.md). An explicit
record always wins over the automatic netting above.

## See also

- [Track contributions](../../guides/track-contributions.md) -- the full workflow.
- [`compare`](compare.md) -- attribution alongside value and price moves.

---

[CLI command reference](index.md)