Once installed you can see Chapter 2, Using Project Manager for a more detailed description of Project Manager and how to use it.

A fresh install of Project Manager will generate a minimal $PROJECT_ROOT/.config/project.nix file containing something like

{ config, pkgs, ... }:

{
  # This value determines the Project Manager release that your
  # configuration is compatible with. This helps avoid breakage
  # when a new Project Manager release introduces backwards
  # incompatible changes.
  #
  # You can update Project Manager without changing this value. See
  # the Project Manager release notes for a list of state version
  # changes in each release.
  project.stateVersion = 0;

  # Let Project Manager install and manage itself.
  programs.project-manager.enable = true;
}

You can use this as a base for your further configurations.

As an example, let us expand the initial configuration file to also install the ‘htop’ and ‘fortune’ packages, install Emacs with a few extra packages available, and enable the user ‘gpg-agent’ service.

To satisfy the above setup we should elaborate the project.nix file as follows:

{ config, pkgs, ... }:

{
  # Packages that should be installed to the project profile.
  project.devPackages = [                            
    pkgs.htop
    pkgs.fortune
  ];

  # This value determines the Project Manager release that your
  # configuration is compatible with. This helps avoid breakage
  # when a new Project Manager release introduces backwards
  # incompatible changes.
  #
  # You can update Project Manager without changing this value. See
  # the Project Manager release notes for a list of state version
  # changes in each release.
  project.stateVersion = 0;

  # Let Project Manager install and manage itself.
  programs.project-manager.enable = true;

  programs.emacs = {                              
    enable = true;
    extraPackages = epkgs: [
      epkgs.nix-mode
      epkgs.magit
    ];
  };

  services.gpg-agent = {                          
    enable = true;
    defaultCacheTtl = 1800;
    enableSshSupport = true;
  };
}

To activate this configuration you can run

project-manager switch

or if you aren’t feeling so lucky,

project-manager build

which will create a result link to a directory containing an activation script and the generated project directory files.

While the project-manager tool doesn’t explicitly support rollbacks at the moment it’s relatively easy to perform one manually. The steps to do so are

To prepare an initial Project Manager configuration for your logged in user, you can run the Project Manager init command directly from its flake.

For example, if you are using the unstable version of Nixpkgs or NixOS, then to generate and activate a basic configuration run the command

$ nix run project-manager/master -- init --switch

For Nixpkgs or NixOS version 23.05 run

$ nix run project-manager/release-23.05 -- init --switch

This will generate a flake.nix and a project.nix file in ~/.config/project-manager, creating the directory if it doesn’t exist.

If you omit the --switch option then the activation won’t happen. This is useful if you want to inspect and edit the configuration before activating it.

$ nix run project-manager/$branch -- init
$ # Edit files in ~/.config/project-manager
$ nix run project-manager/$branch -- init --switch

Where $branch is one of master or release-23.05.

After the initial activation has completed successfully then building and activating your flake-based configuration is as simple as

$ project-manager switch

it’s possible to override the default configuration directory, if you want. For example,

$ nix run project-manager/$branch -- init --switch ~/hmconf
$ # And after the initial activation.
$ project-manager switch --flake ~/hmconf

Overall the basic option types are the same in Project Manager as Home Manager. There are some extra options provided in the file-type submodule.

If you haven’t forked Project Manager yet, then you need to do that first. Have a look at GitHub’s Fork a repo for instructions on how to do this.

Once you have a fork of Project Manager you should create a branch starting at the most recent master branch. Give your branch a reasonably descriptive name. Commit your changes to this branch and when you are happy with the result and it fulfills Section 5.2, “Guidelines” then push the branch to GitHub and create a pull request.

Assuming your clone is at $HOME/devel/project-manager then you can make the project-manager command use it by either

The first option is good if you only temporarily want to use your clone.

If your contribution satisfy the following rules then there is a good chance it will be merged without too much trouble. The rules are enforced by the Project Manager maintainers and to a lesser extent the Project Manager CI system.

If you are uncertain how these rules affect the change you would like to make then feel free to start a discussion in the #project-manager IRC channel, ideally before you start developing.

$ nix-build -A docs.html
$ xdg-open ./result/share/doc/project-manager/index.html

$ nix-build -A docs.manPages
$ man ./result/share/man/man5/project-configuration.nix.5.gz

The commits in your pull request should be reasonably self-contained, that is, each commit should make sense in isolation. In particular, you will be asked to amend any commit that introduces syntax errors or similar problems even if they’re fixed in a later commit.

The commit messages should follow the seven rules, except for "Capitalize the subject line". We also ask you to include the affected code component or module in the first line. That is, a commit message should follow the template

{component}: {description}

{long description}

where {component} refers to the code component (or module) your change affects, {description} is a very brief description of your change, and {long description} is an optional clarifying description. As a rare exception, if there is no clear component, or your change affects many components, then the {component} part is optional. See Example 5.1, “Compliant commit message” for a commit message that fulfills these requirements.

starship: allow running in Emacs if vterm is used

The vterm buffer is backed by libvterm and can handle Starship prompts
without issues.

Finally, when adding a new module, say programs/foo.nix, we use the fixed commit format foo: add module. You can, of course, still include a long description if you wish.

The code in Project Manager is formatted by the nixfmt tool and the formatting is checked in the pull request tests. Run the format tool inside the project repository before submitting your pull request.

Keep lines at a reasonable width, ideally 80 characters or less. This also applies to string literals.

We prefer lowerCamelCase for variable and attribute names with the accepted exception of variables directly referencing packages in Nixpkgs which use a hyphenated style. For example, the Project Manager option services.gpg-agent.enableSshSupport references the gpg-agent package in Nixpkgs.

Project Manager includes a system for presenting news to the user. When making a change you, therefore, have the option to also include an associated news entry. In general, a news entry should only be added for truly noteworthy news. For example, a bug fix or new option doesn’t need a news entry.

If you do have a change worthy of a news entry then please add one in news.nix but you should follow some basic guidelines:

Project Manager includes a basic test suite and it’s highly recommended to include at least one test when adding a module. Tests are typically in the form of "golden tests" where, for example, a generated configuration file is compared to a known correct file.

It’s relatively easy to create tests by modeling the existing tests, found in the tests project directory. For a full reference to the functions available in test scripts, you can look at NMT’s bash-lib.

The full Project Manager test suite can be run by executing

$ nix-shell --pure tests -A run.all

in the project root. List all test cases through

$ nix-shell --pure tests -A list

and run an individual test, for example alacritty-empty-settings, through

$ nix-shell --pure tests -A run.alacritty-empty-settings

However, those invocations will impurely source the system’s nixpkgs, and may cause failures. To run against the nixpkgs from the flake.lock, use instead e.g.

$ nix develop --ignore-environment .#all

Project Manager is only able to set session variables automatically in derivations that extend the ones provided by Project Manager.

If you are using a stable version of Nixpkgs but would like to install some particular packages from Nixpkgs unstable – or some other channel – then you can import the unstable Nixpkgs and refer to its packages within your configuration. Something like

{ pkgs, config, ... }:

let

  pkgsUnstable = import <nixpkgs-unstable> {};

in

{
  project.devPackages = [
    pkgsUnstable.foo
  ];

  # …
}

should work provided you have a Nix channel called nixpkgs-unstable.

You can add the nixpkgs-unstable channel by running

$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgs-unstable
$ nix-channel --update

Note, the package won’t be affected by any package overrides, overlays, etc.

By default Project Manager will install the package provided by your chosen nixpkgs channel but occasionally you might end up needing to change this package. This can typically be done in two ways.