Documentation

Your home folder

On most distros, your home directory accumulates Desktop / Documents / Downloads / Music / Pictures / Videos / Public / Templates as eight loose top-level folders. After six months it's a swamp: where did I save that PDF — Documents? Downloads? Desktop? Margine flips the question. Three top-level folders, each with a clear job. Your save dialogs, screenshot tool, and Nautilus sidebar already point at the right sub-folders by default. You don't configure anything; on first login margine-bootstrap creates the layout once and walks away.

The one-screen picture

Here's the entire tree. Three roots at the top. Everything else lives below.

~/                            ← your home

├── data/                  ← keep-forever stuff (back this up)
│   │
│   ├── personal/          ← Documents target. Your "my files".
│   ├── inbox/
│   │   └── 10-downloads/  ← Downloads target. Default save dir.
│   ├── media/
│   │   ├── photos/        ← Pictures target. Camera, screenshots.
│   │   ├── audio/         ← Music target.
│   │   └── video/         ← Videos target.
│   ├── projects/          ← active creative projects
│   ├── shared/            ← shared with other devices/users
│   └── templates/         ← Office / LibreOffice templates
│
├── dev/                   ← source code. Git repos, sandboxes.
│
└── scratch/               ← disposable. Delete without guilt.

The rule, in one sentence

data is what you'd cry over losing. dev is code (already on GitHub anyway). scratch is trash with a delay.

What Margine wires up for you

None of this needs configuration. On first login the ujust margine-bootstrap step (which the autostart runs once) creates the folders, writes ~/.config/user-dirs.dirs, and registers the Nautilus sidebar bookmarks. Everything just points at the right place from then on.

  • Save dialogs (GTK/GNOME apps, Bazaar installs, Firefox/Zen downloads) default to ~/data/inbox/10-downloads/ — not ~/Downloads.
  • Screenshots (PrintScreen for the menu, Shift+PrintScreen for a region) land in ~/data/media/photos/.
  • GNOME SoundRecorder writes to ~/data/media/audio/.
  • "Documents", "Pictures", "Music", "Videos" in every Save-As dialog already resolve to the ~/data/<...> sub-folders below — the XDG key→path mapping in user-dirs.dirs handles that.
  • Nautilus sidebar shows nine bookmarks (Documents, Downloads, Pictures, Music, Videos, Shared, Projects, Development, Scratch) pointing at the corresponding folders inside data/ / dev/ / scratch/.

Why three roots and not the classic eight?

The eight XDG folders (~/Documents, ~/Downloads, …) are flat at the top level. After a few months you have also ~/Music, ~/Videos, ~/Templates, ~/Public, plus whatever apps drop there (~/snap/, ~/.local/, ~/Desktop/, …) and the distinction between "stuff I made" and "stuff some installer put here" disappears.

Margine groups by intent, not by file type:

  • Backup is one folder. Want to back up everything personal? rsync ~/data/ <target>. Done. You don't have to remember every individual XDG folder.
  • Moving to a new machine is one folder. Same logic.
  • Source code separated. rm -rf ~/dev/old-project never touches a single photo.
  • Scratch is fearless. ~/scratch/ exists so you can dump a 4 GB video export "just to see" and clear it next week without wondering if you needed it.

Where do I put X?

A photo I took, a song I bought, a video I shot
    → ~/data/media/{photos,audio,video}/

A PDF, a Word doc, a scan, anything I made or signed
    → ~/data/personal/

A file I downloaded (Bazaar install, Firefox dl, attachment)
    → ~/data/inbox/10-downloads/  (default; Margine puts it there)

A project I'm actively working on (video edit, CAD job, photoshoot)
    → ~/data/projects/<project-name>/

A repo I cloned, or a sandbox I'm hacking in
    → ~/dev/<repo>/

A test export, a screen recording I'll delete, a random ISO
    → ~/scratch/

A file someone else on my LAN/another PC needs
    → ~/data/shared/

An Office template / LibreOffice template
    → ~/data/templates/

What if I'd rather have the classic Documents / Downloads / ... ?

Free will. Edit ~/.config/user-dirs.dirs by hand (it's plain text) and point the XDG keys wherever you want. The Margine layout is a recommended default, not a lock. xdg-user-dirs-update from the terminal opens the standard tool too.

If you do customize it: run margine-validate-declared-state later to see a clear "drift" warning that you've moved away from the shipped spec. That's informational, not an error.

Resetting the layout

If something gets messed up (you accidentally deleted ~/data/inbox/, or you want to come back to the default after a hand-edit), just run:

ujust margine-bootstrap

It's idempotent. Existing files are left alone, missing folders are recreated, user-dirs.dirs and the Nautilus bookmarks are restored to the shipped values.