File System Organization
FPM organizes ftd files in “packages”.
Package Name
Each package has a name. The name of the package can be either just foo or foo/bar. The former is usually the “account name”, eg the username or the org that owns that package, and the latter is a namespace package.
FPM Home

It is common for people to work on more than one package at a time. In Git, every repo is checked on a folder on its own, with no relationship between folders corresponding to different git repos.

Documents in FPM package can refer to other FPM packages. So if you are working on both packages amitu and amitu/realm for example, it is handy to checkout amitu in a folder named amitu and the package amitu/realm in amitu/realm.

All packages in FPM should be checked out in “fpm home” folder. You can have more than one fpm home if you so desire for whatever reason.

fpm home discovery

fpm tool expects the .fpm.ftd in a fpm home, and traverses up the folder tree till it finds it, that folder is called fpm home.

Note: fpm home is optional. If .fpm.ftd file is not found in the expected location it is assumed that the package is in standalone mode.

Package Folder
A package with name x/y is check-out/expected to be in $FPM_HOME/x/y.
Every package folder has a file FPM.ftd.
.build dir

When a package is built using fpm build, the generated .html etc files are stored in .build folder in the package root, next to FPM.ftd file.

If you are using static site hosting solution, eg Github Pages, Vercel, Cloudflare Pages etc, the content of .build folder has to be uploaded to your static site host.

.packages dir
If the package has a dependency on another package, the dependencies are downloaded and stored in .packages folder.
.history dir

FPM implements history tracking, and creates a snapshot of every file that is modified in .history folder.

You can create a new history snapshot by using fpm sync. If this package uses fpm-repo, content of local system would be synced and history snapshots would be created on fpm-repo server. If other repo like github etc are being used, then all files that have changed in package directory that have changed since last sync will be stored in the .history folder.

.history/.latest.ftd file
This file keeps track of latest timestamp of all files in .history folder. It looks like this:
-- import: fpm

-- fpm.snapshot: FPM.ftd
timestamp: 1638625721072234000

-- fpm.snapshot: foo/index.ftd
timestamp: 1638625721072234000