Configure dob¶

Before we dive into dob and how to really use it, you’ll first want to understand how to configure it.

dob has a robust user configuration. There are lots of settings you can tweak, and there are lots of ways to tweak those settings (like using the CLI, editing a config file, or even setting environment variables).

Let’s start with how to view the config. You can either dump it to the terminal using the CLI, or you can open the config file.

We recommend using the CLI to see all the settings. The config file may not contain settings that have not been changed from their default.

Show the config¶

Run the config show command to see all the settings you can change.

For example:

$ dob config show
+---------+----------+-------------------------------+------------------------------+
| Section |   Name   |        Value <Default>        |             Help             |
+=========+==========+===============================+==============================+
|      db | orm      | sqlalchemy                    | ORM used by dob to interface |
|         |          |                               | with the DBMS. Most likely   |
|         |          |                               | ‘sqlalchemy’.                |
+---------+----------+-------------------------------+------------------------------+
|      db | engine   | sqlite                        | Database management system   |
|         |          |                               | used to manage your data.    |
|         |          |                               | Most likely ‘sqlite’.        |
...

You’ll notice that each config setting belongs to a section, has a name, has a current value (with the default value shown in <brackets> if different), and a bit of help.

Dump a config section¶

You can restrict to a section or even a specific setting by specifying them after the command. E.g.,:

$ dob config show term
+---------+---------------+-----------------+---------------------------------------+
| Section |     Name      | Value <Default> |                 Help                  |
+=========+===============+=================+=======================================+
|    term | editor_suffix | .rst <>         | The filename suffix to tell EDITOR so |
|         |               |                 | it can determine highlighting         |
...

Dump a single setting¶

Or, to see a single setting’s entry, include the setting name:

$ dob config show term use_color
+---------+-----------+-----------------+-------------------------------------------+
| Section |   Name    | Value <Default> |                   Help                    |
+=========+===========+=================+===========================================+
|    term | use_color | True            | If True, use color and font ornamentation |
|         |           |                 | in output.                                |
+---------+-----------+-----------------+-------------------------------------------+

Get and set config settings¶

If you’d like to see just the value, use the get command. For instance:

$ dob config get editor centered
True

To change the value of a setting, use the set command. For instance:

$ dob config set editor centered False
$ dob config get editor centered
False

You can also edit config settings directly in the config file itself.

Find your config file¶

If you’d like to inspect the raw config file, you’ll have to find where it lives.

Run the details command, e.g.,:

$ dob details
You are running dob version 3.0.7
Configuration file at: /home/user/.config/dob/dob.conf
Plugins directory at: /home/user/.config/dob/plugins
Logfile stored at: /home/user/.cache/dob/log/dob.log
Reports exported to: .{format}
Using sqlite on database: /home/user/.local/share/dob/dob.sqlite

Obviously, you’ll find the config at the path shown after “Configuration file at”.

If you really want to impress yourself, you can automate opening the config. Run the environs command to output shell-style VAR=VALUE strings, source that, and use the DOB_CONF variable, e.g.,:
```
$ eval "$(dob env)" && vim $DOB_CONF
```
If you’d like to keep the config file under revision control, feel free to use a symlink at the config file path, and then put the real file in your private repo.

Populate your config file¶

Each config set command will write one value to your config file, but if you’d like to add all settings to your config file, so you can see them all, run config update:

$ dob config update

Then open your config file, and you should see all settings therein.

Note that any comments you may have added to the config file will be preserved.

Change settings at runtime¶

If you want to change configuration settings on the fly, you can do that, too.

You can specify a different configuration file using the DOB_CONFIGFILE variable. You could set it permanently, say, from your startup scripts, or you could set if just for a single command, e.g.,:
```
DOB_CONFIGFILE=path/to/dob.conf dob COMMAND ...
```
Likewise, you can specify config values using environment variables, e.g.,:
```
DOB_CONFIG_DB_ENGINE=sqlite dob stats
```
or using a global CLI option, -C, e.g.,:
```
dob -C db.engine=sqlite stats
```

Refer to dob config --help for more details.