One of the most powerful combinations is self.projectConfigurations.${system}.devShells.project-manager. This provides a shell that has a PATH and other environment that have been produced by the Project Manager configuration. If you use this environment, you can often avoid producing files into your working tree, as the executables available here may be modified to look for their files directly in the Nix store.

To create a new project from scratch, run the following command :

nix run github:sellout/project-manager -- init my-new-project --switch

This will create a new directory called “my-new-project” in the current directory, create a flake and project configuration (.config/project/default.nix) in that directory, and populate it with files as dictated by the project configuration.

See §Configuration for where to go from here.

WARNING: project-manager switch (but no other subcommands) may overwrite files that already exist in your working tree. You should ensure that everything is committed or stashed before integrating Project Manager with an existing project.

Start by creating a basic project configuration by running this from within your project directory:

nix run github:sellout/project-manager

Note that this is similar to the command used by a new project. The differences are that

If your project is already flake-based, this will not overwrite the existing flake, so you will need to modify your flake to provide Project Manager integration.

At a minimum, you need to have

{
  outputs = {nixpkgs, project-manager, self}: let
    system = "x86_64-linux"; # or another system
    pkgs = import nixpkgs {inherit system};
  in {
    projectConfigurations.${system} =
      project-manager.lib.defaultConfiguration {inherit pkgs self};
  }

  inputs = {
    # NB: This version doesn’t have to be current, Project Manager supports many
    #     older Nixpkgs releases as well as unstable (as much as is possible).
    nixpkgs.url = "github:NixOS/nixpkgs/release-24.05";
    project-manager.url = "github:sellout/project-manager";
  }
}

But project manager offers many attributes to integrate with other parts of your flake. For example., you may also include

{
  outputs = {nixpkgs, project-manager, self}: let
    system = "x86_64-linux"; # or another system
    pkgs = import nixpkgs {inherit system};
  in {
    # …

    devShells.${system} = let
        self.projectConfigurations.${system}.devShells
        // {
          # You can user `overrideAttrs` on this to extend this shell.
          default =
            self.projectConfigurations.${system}.devShells.project-manager;
        };

      checks.${system} =
        # This provides a check that files generated by Project Manager are
        # up-to-date, as well as checks for other modules you may have
        # configured (a formatter, linters, etc.)
        self.projectConfigurations.${system}.checks
        // {
          # Any additional checks
        }

      # If your formatter is configured by Project Manager, which is especially
      # useful when using meta-formatters like treefmt-nix.
      # (https://github.com/numtide/treefmt-nix#readme)
      formatter.${system} = self.projectConfigurations.${system}.formatter;
}

If you have all of your non-Project Manager related changes stashed, you can see how the default configuration affects your project by running

nix run github:sellout/project-manager -- switch

You can now see what changes are reflected in your VCS. The most important thing is to check for modified files. For anything that has been modified you can either disable that module in .config/project/default.nix or adjust the configuration there to match what exists in your repository.

Other files may have also been created. You can similarly disable these modules if you want to.

A fresh install of Project Manager will generate a minimal $PROJECT_ROOT/.config/project/default.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.
  home.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 configure programs and services Project Manager must write various things to your project directory. Project Manager will attempt to detect collisions with existing files, but this can be difficult. Whereas Home Manager can rely on symlinks to identify files that have been produced during activation, Project Manager can’t always do this. Files with “repository” persistence must be either hard links or copies (if the project is on a different volume than the Nix store). Project Manager must assume these files can be overwritten. This is why it’s important to ensure that changes are stashed or committed before running project-manager switch.

If there are collisions between existing files and files with “worktree” persistence, these will cause Project manager to terminate before changing any files. (Files with “store” persistence don’t exist in the worktree and thus can never prevent switching.)

For example, suppose you have a wonderful, painstakingly created $PROJECT_ROOT/.git/config and add

{
  # …

  programs.git = {
    enable = true;
    userName = "Jane Doe";
    userEmail = "jane.doe@example.org";
  };

  # …
}

to your configuration. Attempting to switch to the generation will then result in

$ project-manager switch
…
Activating checkLinkTargets
Existing file '/…/.git/config' is in the way
Please move the above files and try again

If you have installed Project Manager using the Nix channel method then updating Project Manager is done by first updating the channel. You can then switch to the updated Project Manager environment.

$ nix-channel --update
…
unpacking channels...
$ project-manager switch

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 24.05 run

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

This will generate a flake.nix and a default.nix file in ./.config/project, 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-24.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 NixOS. A few Project Manager options, however, make use of custom types that are worth describing in more detail. These are the option types dagOf and gvariant that are used, for example, by project.activation.

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 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 Matrix room. 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

{component}: {description}

{long description}

    starship: allow running in Emacs if vterm is used

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

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 currently installs packages into the user environment, precisely as if the packages were installed through nix-env --install. This means that you will get a collision error if your Project Manager configuration attempts to install a package that you already have installed manually, that is, packages that shows up when you run nix-env --query.

For example, imagine you have the hello package installed in your environment

$ nix-env --query
hello-2.10

and your Project Manager configuration contains

project.devPackages = [ pkgs.hello ];

Then attempting to switch to this configuration will result in an error similar to

$ project-manager switch
these derivations will be built:
  /nix/store/xg69wsnd1rp8xgs9qfsjal017nf0ldhm-project-manager-path.drv
[…]
Activating installPackages
replacing old ‘project-manager-path’
installing ‘project-manager-path’
building path(s) ‘/nix/store/b5c0asjz9f06l52l9812w6k39ifr49jj-project-environment’
Wide character in die at /nix/store/64jc9gd2rkbgdb4yjx3nrgc91bpjj5ky-buildenv.pl line 79.
collision between ‘/nix/store/fmwa4axzghz11cnln5absh31nbhs9lq1-project-manager-path/bin/hello’ and ‘/nix/store/c2wyl8b9p4afivpcz8jplc9kis8rj36d-hello-2.10/bin/hello’; use ‘nix-env --set-flag priority NUMBER PKGNAME’ to change the priority of one of the conflicting packages
builder for ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-project-environment.drv’ failed with exit code 2
error: build of ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-project-environment.drv’ failed

The solution is typically to uninstall the package from the environment using nix-env --uninstall and reattempt the Project Manager generation switch.

You could also opt to uninstall all of the packages from your profile with nix-env --uninstall '*'.

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

You are most likely trying to configure something that uses dconf but the DBus session isn’t aware of the dconf service. The full error you might get is

error: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown: The name ca.desrt.dconf was not provided by any .service files

or

error: GDBus.Error:org.freedesktop.systemd1.NoSuchUnit: Unit dconf.service not found.

The solution on NixOS is to add

programs.dconf.enable = true;

to your system configuration.

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.