Built-in package manager vs manual ~/.atom/packages clone for pinned commits

Answer to the Core Question

Which approach preserves dependency metadata when the registry is offline? – The built‑in apm manager records a package’s version and dependencies in its local package.json, but it will still try to reach the Atom registry if any dependency is missing locally. When the registry is unreachable the manager cannot resolve new dependencies, so the only way to guarantee a fully deterministic set of dependencies is to use manual git clones that contain every required package.json and the exact code you want.

Activation Order: Manager‑Installed vs Manual Clones

Atom loads packages in alphabetical order of the directory names under ~/.atom/packages. Packages installed via apm are placed in the same directory tree, so they follow the same rule. The registry does not influence activation order; only the directory name matters. Thus, a manually cloned package will be activated in the same sequence as a manager‑installed one, unless you rename the directory to force a different order.

Pinning a Commit Without Triggering Updates

After cloning a repository, check out the desired commit:

cd ~/.atom/packages/<pkg-name>
git checkout <commit‑sha>

Set the version field in the package’s package.json to the same SHA or to a static string that identifies the state. Atom will display that value in apm list --installed --verbose, and the built‑in manager will not attempt to update it because the version no longer matches a registry entry.

Verification Commands

• apm list --installed --verbose – shows the version field for every package.
• apm info <pkg-name> – displays the stored package.json metadata, useful to confirm that dependencies match the local clone.
• apm install <pkg-name> --no-color while the registry is offline – should fail for manager‑installed packages but succeed for a pre‑cloned directory.

After boot, open the Atom log (File → Open Log) to verify that the manually cloned package appears in the activation sequence and that no update prompts are shown.

When to Prefer Manual Clones

• The Atom registry is down or unreachable.
• You need a specific commit or a local development branch.
• You want full control over the dependency tree without apm pulling new versions.

When to Use the Built‑In Manager

• The registry is reachable and you are comfortable with its automatic update and dependency resolution workflow.

Diagnostic Question

Do any of your packages declare peer dependencies that are not currently installed locally? Missing peers can break activation and may influence whether a manual clone is the safer choice.