-*- mode: org -*-

* About

=Emacs-Guix= (aka =guix.el=) provides various features and tools
for [[http://www.gnu.org/software/guix/][GNU Guix]] package manager.

It allows you to manage your Guix profile(s) from Emacs: to install,
upgrade and remove packages, to switch and remove profile generations,
to display all available info about packages and to do many other
things.

If you are [[https://github.com/emacs-evil/evil][Evil]] user, note that [[https://github.com/emacs-evil/evil-collection][Evil Collection]] provide key bindings for
Emacs-Guix.

This README provides only a basic overview on Emacs-Guix, for a full and
detailed description, see the [[https://emacs-guix.gitlab.io/website/manual/latest/html_node/index.html][info manual]] that comes with it.

In short, Emacs-Guix provides the following features:

- Interface for:

  + profiles

  + profile generations (including system generations for GuixSD)

  + packages

  + services

  + package licenses

  + package and service locations

  + [[/gnu/store]] items

- Magit-like popup interface for all guix shell commands (=M-x guix=).

- Modes to view logs of package builds (=guix-build-log-mode= and
  =guix-build-log-minor-mode=).

- Minor mode to "prettify" store file names (to replace hash parts with
  "…").

- Shell completions for all guix commands and options (for =M-x shell=
  and =M-x eshell=).

- Minor mode with additional functionality for =scheme-mode= to work
  with Guix .scm files, particularly with package modules
  (=guix-devel-mode=).

On the following screenshot you can see one of the mentioned features,
namely: "list" and "info" interface for Guix packages (this screenshot
was made for an early version of Emacs-Guix, the interface has slightly
changed since then).

[[http://i.imgur.com/gRcu14n.png]]

([[https://gitlab.com/alezost-emacs/alect-themes][alect-light]] theme is used there).

* Installation

Emacs-Guix can be installed using Guix, from [[http://melpa.org/][MELPA]], or it can be used
from a git checkout.  *Note* that it is not recommended to mix several
installations (in particular, Guix and MELPA), as it may lead to
incompatibilities in the source (=.scm=) and compiled (=.go=) Guile
files (see [[https://github.com/alezost/guix.el/issues/21][issue 21]]).

** Guix

Just use:

#+BEGIN_SRC sh
guix package -i emacs-guix
#+END_SRC

** MELPA

If you added "melpa" or "melpa-stable" archives to =package-archives= as
it is described on the [[http://melpa.org/#/getting-started][MELPA Getting Started]] page, you can install
"emacs-guix" using =M-x package-install= or =M-x list-packages=
commands.

** Git checkout

Also you can clone this git repository and use Emacs-Guix from this git
checkout (see the info manual for details).

Finally, if you have the git checkout, you can install Guix package for
the current commit of Emacs-Guix using [[file:guix.scm]] file:

#+BEGIN_SRC sh
guix package --install-from-file=guix.scm
#+END_SRC

* Usage

Call =M-x guix-help= to get a summary of all available commands.
Here is an *incomplete* list of them:

- Show packages and their definitions:

  : M-x guix-all-packages
  : M-x guix-installed-user-packages
  : M-x guix-installed-system-packages
  : M-x guix-packages-by-name
  : M-x guix-packages-by-license
  : M-x guix-packages-by-location
  : M-x guix-package-from-file
  : M-x guix-search-by-name
  : M-x guix-search-by-regexp

  : M-x guix-package-locations
  : M-x guix-find-package-definition

- Show profiles and profile generations:

  : M-x guix-profiles
  : M-x guix-generations
  : M-x guix-system-generations

- Show services and their definitions:

  : M-x guix-all-services
  : M-x guix-services-by-name
  : M-x guix-services-by-regexp
  : M-x guix-services-by-location

  : M-x guix-service-locations
  : M-x guix-find-service-definition

- Show store items:

  : M-x guix-store-live-items
  : M-x guix-store-dead-items
  : M-x guix-store-failures
  : M-x guix-store-item-referrers
  : M-x guix-store-item-references
  : M-x guix-store-item-requisites
  : M-x guix-store-item-derivers

- Show/browse package licenses:

  : M-x guix-licenses
  : M-x guix-browse-license-url
  : M-x guix-find-license-definition

- Magit-like interface:

  : M-x guix

- Miscellaneous commands:

  : M-x guix-help
  : M-x guix-about
  : M-x guix-pull
  : M-x guix-prettify-mode
  : M-x guix-build-log-mode
  : M-x guix-devel-mode