Knowledge Base:Edit a configuration file

From Gentoo Wiki
Jump to:navigation Jump to:search


Step by step guide to edit a configuration file.


All the time.


Configuration files are the default method to configure most software. Use a text editor to edit them. The default text editor in Gentoo is nano.


Different text editors may be used on the command line to edit configuration files. Nano will be installed by default on a Gentoo installation, but it is ultimately up to the user what editor to install and use.

Nano will probably be the most accessible editor for beginners, because it behaves a little like many GUI editors, and provides a help bar at the bottom of the screen by default.

The sudo command may be needed to edit system configuration files owned by root.

Always backup important data before making modifications. To quickly backup a configuration file before editing it, a copy may be created with a timestamp appended to the filename. This will allow to always be able to see when the backup was made (even if the file is subsequently moved), and allow to automatically retain several backed up versions. In bash for example (this could be made into a function):

user $cp <filename> <filename>.bak-$(date +%FT%T)


Start Emacs by typing emacs in the terminal, followed by file path and name:

user $emacs <filename>

Move around with the arrow keys, insert text freely. To save a file, type C-x C-s (Ctrl+x followed by Ctrl+s).

To close Emacs, type C-x C-c (Ctrl+x followed by Ctrl+c).

For "quick-start" documentation directly in Emacs, type: C-h t (Ctrl+h followed by t). For further help on how to use Emacs, type C-h r (Ctrl+h followed by r).

For more information online:


Start Nano by typing nano in the terminal, followed by file path and name:

user $nano <filename>
Prior to nano 4.0, when editing configuration files, always pass nano the -w option. Without this option, long lines are wrapped by inserting newlines - this will often break configuration files.

Nano now shows the content of the text file. Navigate through the text with the arrow keys and make edits as desired.

At the bottom Nano shows shortcuts for common actions (save, exit, etc.). The shortcut to save a file is shown as "^O". Users must prefix the shortcut with the Ctrl key, so to save a file press Ctrl+O. To exit press Ctrl+X.


Start Vim by typing vim in the terminal, followed by file path and name, using vi should also be possible:

user $vim <filename>

Vim will create the file upon saving if no such file exists yet.

Vim is a modal editor, it will start in command mode, and can be switched between this and insert mode. Use h, j, k, l (by default) to move the cursor in command mode. Enter insert mode, to enter text, by pressing i, and return to command mode by pressing Esc. Save by opening the Vim command line, by pressing :, then w, Enter. Quit with :, q, Enter. Add ! after q to quit without saving changes.

See Vim/Guide for more instructions on using Vim.

See also

  • Backup — prevent loss of data by ensuring it can be recovered.
  • Etckeeper — a collection of tools to store /etc in a VCS (version control) repository, to keep a backup of changes to system configuration files
  • Text editor — a program to create and edit text files.