# Configuration

Kupferbootstrap uses [toml](https://en.wikipedia.org/wiki/TOML) for its configuration file.

The file can either be edited manually or managed via the {doc}`cli/config` subcommand.

You can quickly generate a default config by running {code}`kupferbootstrap config init -N`.

## File Location

The configuration is stored in `~/.config/kupfer/kupferbootstrap.toml`, where `~` is your user's home folder.

Kupferbootstrap needs to create a number of folders, e.g. to download `PKGBUILDs.git` and store binary packages.
By default, all of those folders live inside `~/.cache/kupfer/`.

See also the `[paths]` section in your config.

## Sections

A config file is split into sections like so:

```toml
[pkgbuilds]
git_repo = "https://gitlab.com/kupfer/packages/pkgbuilds.git"
git_branch = "dev"

[pacman]
parallel_downloads = 3
```

Here, we have two sections: `pkgbuilds` and `pacman`.

## Flavours

Flavours are preset collections of software and functionality to enable,
i.e. desktop environments like [Gnome](https://en.wikipedia.org/wiki/GNOME)
and [Phosh](https://en.wikipedia.org/wiki/Phosh).

## Profiles

The last section and currently the only one with subsections is the `profiles` section.

A profile is the configuration of a specific device image. It specifies (amongst others):

- the device model
- the flavour (desktop environment)
- the host- and user name
- extra packages to install

Using a profile's `parent` key,
you can inherit settings from another profile.

This allows you to easily keep a number of slight variations of the same target profile around
without the need to constantly modify your Kupferbootstrap configuration file.

You can easily create new profiles with
[kupferbootstrap config profile init](../cli/config/#kupferbootstrap-config-profile-init).

Here's an example:

```toml
[profiles]
current = "graphical"

[profiles.default]
parent = ""
device = "oneplus-enchilada"
flavour = "barebone"
pkgs_include = [ "wget", "rsync", "nano", "tmux", "zsh", "pv", ]
pkgs_exclude = []
hostname = "kupferphone"
username = "prawn"
size_extra_mb = 800

[profiles.graphical]
parent = "default"
flavour = "phosh"
pkgs_include = [ "firefox", "tilix", "gnome-tweaks" ]
size_extra_mb = "+3000"

[profiles.hades]
parent = "graphical"
flavour = "phosh"
hostname = "hades"

[profiles.recovery]
parent = "default"
flavour = "debug-shell"

[profiles.beryllium]
parent = "graphical"
device = "xiaomi-beryllium-ebbg"
flavour = "gnome"
hostname = "pocof1"
```

The `current` key in the `profiles` section controlls which profile gets used by Kupferbootstrap by default.

The first subsection (`profiles.default`) describes the `default` profile
which gets created by [config init](../cli/config/#kupferbootstrap-config-init).

Next, we have a `graphical` profile that defines a couple of graphical programs for all but the `recovery` profile,
since that doesn't have a GUI.

### `size_extra_mb`

Note how `size_extra_mb` can either be a plain integer (`800`) or a string,
optionally leading with a plus sign (`+3000`),
which instructs Kupferbootstrap to add the value to the parent profile's `size_extra_mb`.

### `pkgs_include` / `pkgs_exclude`

Like `size_extra_mb`, `pkgs_include` will be merged with the parent profile's `pkgs_include`.

To exclude unwanted packages from being inherited from a parent profile, use `pkgs_exclude` in the child profile.

```{hint}
`pkgs_exclude` has no influence on Pacman's dependency resolution.
It only blocks packages during image build that would usually be explicitly installed
due to being listed in a parent profile or the selected flavour.
```