Blog · 2026-05-19 · 7 min read

Astrophotography archive folder structure: date-first vs target-first

Every imager eventually faces the question "how should I organize my archive?" The two layouts most people end up with are date-first and target-first. Neither is wrong, and the choice matters less than people think — but the trade-offs are real.

The two layouts in practice

Both layouts use the same building blocks — a date, a target, a frame type — but stack them in opposite orders. Date-first leads with when you imaged; target-first leads with what you imaged.

Date-first:

archive/
├── 2024-08-13/
│   ├── Light/
│   │   ├── M81/
│   │   │   ├── M81_L_300s_001.fit
│   │   │   └── M81_L_300s_002.fit
│   │   └── NGC7000/
│   │       └── NGC7000_Ha_600s_001.fit
│   ├── Flat/
│   └── Dark/
├── 2024-08-14/
│   └── Light/
│       └── M81/
└── 2024-08-15/
    └── Light/
        └── M31/

Target-first:

archive/
├── M81/
│   ├── 2024-08-13/
│   │   └── Light/
│   │       ├── M81_L_300s_001.fit
│   │       └── M81_L_300s_002.fit
│   └── 2024-08-14/
│       └── Light/
├── M31/
│   └── 2024-08-15/
│       └── Light/
└── NGC7000/
    └── 2024-08-13/
        └── Light/

The date-first tree reads like a journal: open a date, see what you shot that night. The target-first tree reads like an inventory: open a target, see every night you've spent on it. Same data, different hinge.

Why date-first emerges first

Most sequencers default to date-organized output. NINA, SGP, APT — they all root captures under a session date by default. Frame types and target names appear as subfolders or filename fragments, but the top-level grouping is the night. After a few months, the archive looks like a chronological diary of your imaging life, and you didn't have to do anything to make it that way.

This is fine. The session is the natural unit of work: you set up, you image, you tear down. A folder per session matches how you actually use the rig.

Why target-first appears later

The first time you re-process a target across multiple nights, date-first starts to chafe. "All my M31 lights" is one folder in a target-first layout. With date-first it's spread across thirty session folders, and pulling them together means dragging files into a staging area every time you want to stack — or relying on stacking software that crawls a folder tree looking for matching OBJECT values.

So people start either (a) restructuring new sessions target-first as they capture, or (b) maintaining a parallel "by-target" tree of shortcuts or symlinks that points back into the date-first archive. Both work. Both are extra labour you didn't have on day one.

What changes with archive age

The right layout drifts as the archive grows:

Year 1. Date-first is fine. You haven't re-processed enough to feel the cost of scattering frames across sessions, and the chronological view tells the story of your learning curve clearly.
Years 2–3. Target-first starts paying off. You've returned to M31, M81, the Veil, and a couple of widefield Ha regions enough times that pulling lights together is a regular operation, not a one-off.
Year 5+. You really want both — or you want a tool that doesn't care because it reads the layout from the FITS headers rather than the folder names. See folder schemas for the layouts Photon Ledger parses directly.

The shape of the question changes, too. Year-one questions are "what did I shoot last weekend?" Year-five questions are "how many hours of Ha do I have on the Cygnus region across all rigs?" One layout answers each well; neither layout answers both well.

Calibration frame organization

Both layouts need a strategy for darks, flats, and biases — and the strategy is mostly independent of the lights layout. A few patterns that work:

Per-rig calibration library at the archive root. A single calibration/ folder, broken down by camera, gain, temperature, and exposure. Lights point at it implicitly via FITS headers. Good when your rigs are stable.
Dated calibration folders per session. Each session folder contains its own Flat/ and Dark/ beside the Light/ tree. Good when flats need to match the exact optical train of that night (filter swaps, focuser movement, dew).
Master calibration files versioned by gain/temp/exposure. Stacked masters live separately from the raw calibration frames. The masters are what your processing pipeline consumes; the raw frames stay archived in case you ever need to re-stack with a different rejection algorithm.

Most archives end up with a mix: session flats next to the lights (because they have to match), plus a library of master darks and bias frames at the root (because those are stable for months).

Migrating between layouts

Practical advice: don't. Trying to reorganize a 10,000-frame archive by moving files breaks every stack history reference, every external link from a processing log, every checksum manifest you may have generated, and any backup software that tracks files by path rather than content hash. The disruption is large; the payoff is "the folder names look nicer."

Better to leave the files where they are and use a tool that reads the FITS headers. OBJECT, DATE-OBS, FILTER, and IMAGETYP are all you need to construct any view of the archive — by target, by date, by filter, by rig — without moving a single byte. See the FITS header reference for the fields involved.

If you really must restructure, do it once, for new captures only, going forward. Don't backfill.

What to do if your folder names disagree with FITS headers

It will happen. The folder says M31/ but the OBJECT header says Andromeda. Or the folder is 2024-08-13/ but DATE-OBS reads 2024-08-14 because you crossed midnight UTC. Or you typed NGV7000 at 3am and didn't notice until the import.

Trust the header. The mount knew where it was pointed; the camera knew what time it was; the filter wheel knew which slot it had selected. The folder name is whatever you typed in the sequencer, possibly while tired. Folder structure is a hint, not authority.

This is why metadata-driven tools don't try to normalise folder names — they read each file and let the header win.

Recommendation

Use whatever your sequencer produces by default. Don't fight it. If NINA writes date-first, let it write date-first. If your workflow forces target-first, fine. Pick one, stay consistent, and stop tinkering with the layout.

For analytics — totals, comparisons, "where did the time go" — use a tool that reads FITS headers rather than relying on folder names. The folders are for humans browsing in Finder; the headers are for software counting frames.

Reorganizing an existing archive is rarely worth the risk. The folder layout matters less than the metadata you're already writing on every exposure.