# -*- mode: org; coding: utf-8; -*-

#+title: guix-manage

* Overview

guix-manage is an opinionated wrapper for Guix which facilitates a profile-based
package management strategy. This allows one, for example, to organize similar
sets of packages into separate manifests to manage together, and to keep these
manifests under source control. It also allows keeping around development
profiles in a unified, easily-upgradable way. guix-manage also takes charge of
the system and home profiles, as well as handling _guix pull_.

Rather than the upgrade strategy of invoking ~guix upgrade~, which upgrades each
package (and its inputs) separately, guix-manage uses completely re-installs the
profile each time its upgraded. From a practical standpoint, this means very
little, but it does match the way ~guix system/home reconfigure~ works.

* Usage

** Config Directory Structure

To use guix-manage, one must first sort one's profile manifests into a specific
filesystem hierarchy and put them somewhere on the system. By default,
guix-manage will look for these files at _~/.config/guix/_, but they can be put
anywhere and the location passed on the commandline with the _--config-dir_
setting. This can also be modified in the guix-manage config file stored at
_~/.config/guix-manage_, which is a simple s-expression based config file.
Here's a sketch of the expected directory structure. Note that all names are
literal except those enclosed in brackets.

- home/
  - config.scm
- manifests/
  - [profile1]/
    - manifest.scm
  - [profile2]/
    - [subprofile1]/
      - manifest.scm
    - manifest.scm
- system/
  - [hostname]-config.scm

** Filename Conventions

- the home config file is called _config.scm_
- profile manifests are called _manifest.scm_
- system config files are called _[hostname]-config.scm_

** Profiles Proper

Profiles themselves are by default installed at _~/.guix-profiles_, but this can
be changed with the _--profiles-dir_ setting. This also has a parallel in the
guix-manage config file. Profiles are named automatically after the name of
the directory in which their manifest is found. For example, if a manifest is at
_[config-dir]/profiles/python/manifest.scm_, it will be installed to
_[profiles-dir]/python/_. Subdirectories are named similar, with their immediate
directory following the parent directory and a hyphen. So, continuing the above
example, if one had a _python/dev/manifest.scm_, it would be installed at
_[profiles-dir]/python-dev/_.

It is important to know these naming conventions because they are how a profile
is referenced at the commandline when passed as an argument.

** Commands

*Note:* guix-manage is alpha software and not all commands are implemented. Only
_upgrade_ and _gc_ are currently implemented.

- add :: Add a CSV list of packages to a provided manifest
- create :: Create a profile with the provided CSV list of packages
- delete :: Delete a profile manifest and its primary profile directory
- gc :: Garbage collect profiles
- remove :: Remove a CSV list of packages from a profile's manifest
- upgrade :: Upgrade profiles

By default, _upgrade_ and _gc_ operate on all profiles; however, this can be
manipulated with the _--include_ and _--exclude_ settings. These also have
parallels in the guix-manage config file.

For more detailed information on usage of specific commands, see the help text.

* Miscellanea

guix-manage does not ship with a script to source profiles at login as the
author feels her management strategy is sinful and wrong and should not be
emulated. However, if you wish to do so, you may take a look at the bash files
in [[https://git.trees.st/Marie-Joseph/guix-config][her config-dir]].

* Develpment Status

guix-manage is still alpha software. It started as an entirely personal project,
and it remains to be seen if anyone else will even want to use it. Regardless,
keep in mind that things may change or break at any time. Feedback is immensely
welcome, and can be sent to me however you can get in touch.

** TODO
- [X] match pre-rewrite featureset (upgrade and gc)
- [ ] implement add
- [ ] implement create
- [ ] implement delete
- [ ] implement remove
- [ ] write tests
- [ ] write proper documentation?