This is not a beginner tutorial – if you’ve never used vim or neovim before then there plenty of videos, blogs and even books to help you get started. Also, if you have a working installation of [neo]vim, then you can also start it and type: :Tutor (including the colon) and press enter and follow the instructions.

Anyway, lets dig in. First port of call, as always, is the manual.

:help

I wont’ reproduce the whole help file here, but this first page is super useful, as it tells you how to find specific information, like on a specific command or option:

help.txt        Nvim

                        VIM - main help file
                                                                         k  
      Move around:  Use the cursor keys, or "h" to go left,            h   l
                    "j" to go down, "k" to go up, "l" to go right.       j
Close this window:  Use ":q<Enter>".                                        
   Get out of Vim:  Use ":qa!<Enter>" (careful, all changes are lost!).
        
Jump to a subject:  Position the cursor on a tag (e.g. bars) and hit CTRL-].
   With the mouse:  Double-click the left mouse button on a tag, e.g. bars.
        Jump back:  Type CTRL-O.  Repeat to go further back.
                                                
Get specific help:  It is possible to go directly to whatever you want help
                    on, by giving an argument to the :help command. 
                    Prepend something to specify the context:  help-context   
        
                          WHAT                  PREPEND    EXAMPLE
                      Normal mode command                  :help x
                      Visual mode command         v_       :help v_u
                      Insert mode command         i_       :help i_<Esc>
                      Command-line command        :        :help :quit
                      Command-line editing        c_       :help c_<Del>
                      Vim command argument        -        :help -r
                      Option                      '        :help 'textwidth'
                      Regular expression          /        :help /[
                    See help-summary for more contexts and an explanation.

We can make the help full screen with :only.

Before we start adding our own stuff, lets have a quick look at what gets included by default. :help initialization shows a serious list of stuff that goes on under the hood when Neovim is started.

Item 4. mentions default-mappings and default-autocmds, take a quick look at those to see what’s going on.

One little note, if you’re going to get deep into Neovim, I recommend you get used to Lua. This means that the mapping functions end up looking different. Instead of adding :noremap F3 i to your init.vim, you put vim.keymap.set('F3','i') in your init.lua.

On the subject of key mappings, there are a few useful tools to keep in mind:

What is a repository?

This is an important question, because answering it explains where a lot of the different fields or tags come from when you’re describing how to select packages.

A repository is just a web server, with files arranged in a specific way that allows apt to collect all the metadata about all the hosted packages and then download the one you want.

Lets take a look at sources.list to find one, the default for Debian 12 (Bookworm) is:

deb http://deb.debian.org/debian bookworm main contrib non-free-firmware non-free
deb http://deb.debian.org/debian bookworm-updates main contrib non-free-firmware non-free
deb http://security.debian.org/debian-security bookworm-security main contrib non-free-firmware non-free

so the first deb just tells us this repository contains the binary files, the only other option is deb-src, which means instead it contains the source code. The next bit http://deb.debian.org/debian is the url for the repository, so before we look the rest of the line, lets look there:

As you can see it’s just a list of files and folder, and conveniently the owner of the repo has implemented a nice web interface so we can see that. The critical info is in the dists/ folder:

There’s quite a few things in here, but actually less than it first appears. So there are versions of debian referred to in 3 different ways:

• Version – the 3 Debian XX.YY folders at the top
• Release Codename – bookworm, trixie etc.
• Suite names or release aliases – stable, testing etc.

You also have a sub suite or sub release for some combination of

• backports
• backports-sloppy
• updates
• proposed-updates

Lets open up bookworm

Notice that the 4 names of the folders at the bottom match the last 4 values on the deb line, but for now well have a look at Release (it’s a plain text file)

Origin: Debian
Label: Debian
Suite: stable
Version: 12.11
Codename: bookworm
Changelogs: https://metadata.ftp-master.debian.org/changelogs/@CHANGEPATH@_changelog
Date: Sat, 17 May 2025 09:13:04 UTC
Acquire-By-Hash: yes
No-Support-for-Architecture-all: Packages
Architectures: all amd64 arm64 armel armhf i386 mips64el mipsel ppc64el s390x
Components: main contrib non-free-firmware non-free
Description: Debian 12.11 Released 17 May 2025
MD5Sum:
 0ed6d4c8891eb86358b94bb35d9e4da4  1484322 contrib/Contents-all
 d0a0325a97c42fd5f66a8c3e29bcea64    98581 contrib/Contents-all.gz
 f49a4e0893e46866e12d086ec218fd81   840868 contrib/Contents-amd64
 06c8860da678334327980e51b5c1780b    60955 contrib/Contents-amd64.gz
 ...

Now we’re getting somewhere. This has a lot of useful data laid out in black and white

Lets drill a bit deeper. If you do into main/binary-amd64/ the, download and extract Packages.gz you’ll get another plain text file with a massive list of data about the packages you can install, here’s an excerpt:

...
Package: apt
Version: 2.6.1
Installed-Size: 4232
Maintainer: APT Development Team <deity@lists.debian.org>
Architecture: amd64
Replaces: apt-transport-https (<< 1.5~alpha4~), apt-utils (<< 1.3~exp2~)
Provides: apt-transport-https (= 2.6.1)
Depends: adduser, gpgv | gpgv2 | gpgv1, libapt-pkg6.0 (>= 2.6.1), debian-archive-keyring, libc6 (>= 2.34), libgcc-s1 (>= 3.0), libgnutls30 (>= 3.7.5), libseccomp2 (>= 2.4.2), libstdc++6 (>= 11), libsystemd0
Recommends: ca-certificates
Suggests: apt-doc, aptitude | synaptic | wajig, dpkg-dev (>= 1.17.2), gnupg | gnupg2 | gnupg1, powermgmt-base
Breaks: apt-transport-https (<< 1.5~alpha4~), apt-utils (<< 1.3~exp2~), aptitude (<< 0.8.10)
Description: commandline package manager
Description-md5: 9fb97a88cb7383934ef963352b53b4a7
Tag: admin::package-management, devel::lang:ruby, hardware::storage,
 hardware::storage:cd, implemented-in::c++, implemented-in::perl,
 implemented-in::ruby, interface::commandline, network::client,
 protocol::ftp, protocol::http, protocol::ipv6, role::program,
 scope::application, scope::utility, suite::debian, use::downloading,
 use::organizing, use::playing, use::searching, works-with-format::html,
 works-with::audio, works-with::software:package, works-with::text
Section: admin
Priority: required
Filename: pool/main/a/apt/apt_2.6.1_amd64.deb
Size: 1372852
MD5sum: 2a077296b9b9f4f8b027f86d9500192b
SHA256: 6ea03cbbc7a7bfcee601c9fb08d4e026fd522ede5350561f06867ad9c0a0fa6b                                                                                                                 

Package: apt-doc
Source: apt
...

Here you’ve got the name of the package, it’s version, processor architecture and dependencies and some metadata like the Description, Tags, Section (for a categorised list). The file hashes at the end are used by apt to download the file.

More reading:

• Apt Configuration: https://wiki.debian.org/AptConfiguration#apt_preferences_.28APT_pinning.29
• Apt preferences (ie. apt pinning) https://manpages.debian.org/buster/apt/apt_preferences.5.en.html
• APT Repositories Explained https://gist.github.com/CodingKoopa/3b30afe8c91e3950f6b124cd2abe3b6b
• apt-cache policy
• apt-cache policy [packagename]

However, on most systems you’ll have to work a little harder than just

./occ upgrade

On my system there are 2 main problems:

• You don’t generally login as the same user as the Nextcloud web service – as I’m using a Debian system the correct user is www-data.
• It needs to start PHP to run the command, which by default doesn’t include the APCu module when you start it from the command line, so we need to fix that.

This is the command I use:

sudo -u www-data php --define apc.enable_cli=1 /var/www/nextcloud/occ upgrade

And a few of the other commonly-used commands after updating (the Administration Overview screen will tell you which of these you need to run:

sudo -u www-data php --define apc.enable_cli=1 /var/www/nextcloud/occ maintenance:mode --on

sudo -u www-data php --define apc.enable_cli=1 /var/www/nextcloud/occ maintenance:mode --off

sudo -u www-data php --define apc.enable_cli=1 /var/www/nextcloud/occ maintenance:repair --include-expensive

sudo -u www-data php --define apc.enable_cli=1 /var/www/nextcloud/occ db:add-missing-indices

This is an issue if you have customised that configuration file on your system – the system doesn’t know whether it should keep your version, use the new one, or something else. So it asks you to decide what to do about it.

I’m using Debian, which uses the dpkg package management system – that name may be unfamiliar, but if you’ve used any of the Debain family (Ubuntu, Mint, MX, elementary etc.) you will have used one of the friendlier wrappers around it: apt or apt-get.

Today, it’s the Collabora Office configuration file that has been updated:

Configuration file '/etc/loolwsd/loolwsd.xml'
 ==> Modified (by you or by a script) since installation.
 ==> Package distributor has shipped an updated version.
   What would you like to do about it ? Your options are:
    Y or I : install the package maintainer's version
    N or O : keep your currently-installed version
      D    : show the differences between the versions
      Z    : start a shell to examine the situation
 The default action is to keep your current version.
*** loolwsd.xml (Y/I/N/O/D/Z) [default=N] ?

• The first option is self-explanatory – you’ll lose any customizations you’ve made, but that might be OK for you.
• Keeping your currently-installed version is usually OK – well designed software shouldn’t break because it’s missing a line in an old configuration file.

In either case the system will keep a copy of the one you don’t pick, so you can change your mind later. If you choose to use the package mantainer’s version, there will be a copy of your old one with .dpkg-old added to the filename. If you keep you own config file, the package maintainer’s version will be saved alongside it, with .dpkg-dist added to the filename.

• Choosing option D can help you decide – but ultimately doesn’t resolve the situation.
• Option Z is the point of today’s post – this is how you can fix the situation.

Lets hit Z, and this is what I get:

 The default action is to keep your current version.
*** loolwsd.xml (Y/I/N/O/D/Z) [default=N] ? Z
Useful environment variables:
 - DPKG_SHELL_REASON
 - DPKG_CONFFILE_OLD
 - DPKG_CONFFILE_NEW
Type 'exit' when you're done.
root@waldorf:/# 

The system tells you about 3 environment variables that might be useful to help fix the situation. here I’ve use the echo command (with a $ before the environment variable name) to see what’s in them:

root@waldorf:/# echo $DPKG_SHELL_REASON
conffile-prompt
root@waldorf:/# echo $DPKG_CONFFILE_OLD
/etc/loolwsd/loolwsd.xml
root@waldorf:/# echo $DPKG_CONFFILE_NEW
/etc/loolwsd/loolwsd.xml.dpkg-new

DPKG_CONFFILE_PROMPT isn’t much use to us, but the other two are. We can start a program to compare and merge the differences between the two. I’m using Neovim in diff mode – there are lots of otherways of doing this – I’d suggest you do your research and find your preferred merge tool or text editor.

root@waldorf:/# nvim -d $DPKG_CONFFILE_OLD $DPKG_CONFFILE_NEW

I wont to get into the details of how to use [Neo]vim, but if you’re already a vim user and haven’t used diff mode before, these commands will get you started. You can find more info in the documentation.

Note that the last two commands will make the files the same at that point

Modifiy one of the files (I typically modify my old file – pulling the changes from the new one that I want, and leaving the ones that I don’t), then save and exit your text editor or mergetool

Type exit at the prompt, then the system will ask you again what you want to do:

*** loolwsd.xml (Y/I/N/O/D/Z) [default=N] ?

In this case I’ll choose N or O because I’ve made the changes I want to the original config file.