What does :set background=dark do?

Question

I didn't put color xxx in my .vimrc. So I see this when I first open my .vimrc.

:color gives me default here.

Then I type :color darcula. And it changes to this.

:color gives me darcula here (naturally).

Then I type :set background=dark. And it changes to this.

:color gives me default here (amazingly).

So my question is, what exactly does :set background=dark do?

I tried :h background and didn't find anything helpful. I understand that this command doesn't actually change the background, only vim will change colors accordingly. But I still want to ask this question. Because I'm really happy with the color after :color darcula and :set background=dark so I wonder how to write my own color scheme without having to put set background=dark in my .vimrc.

I took advice from @statox and put set background=dark at the last line of my darcula.vim. Then color darcula gives me the third screenshot. However when I put it at the first line, color darcula gives me the second screenshot. Also set bg=dark changes it to the third screenshot.

I assumed by putting it at the first line, I'm telling vim that this colorscheme is designed for a dark background. By putting it at the last line, on the contrast, I let vim assume that this colorscheme is designed for a light background and then make vim change some of it by itself (when it processes the last line).

If what I assume happened is true, my question is still unanswered. What exactly did vim change, when I use set bg=dark AFTER it has loaded a light colorscheme?

My entire vim configuration is available at https://github.com/MichaelMa2014/.vim

Answer 1

What happens when you :set background

The basic mechanism by which :set background works is actually pretty simple, and it is documented (although not particularly clearly) in :help 'background'.

When 'background' is set Vim will adjust the default color groups for the new value. But the colors used for syntax highlighting will not change. g:colors_name
When a color scheme is loaded (the "g:colors_name" variable is set) setting 'background' will cause the color scheme to be reloaded. If the color scheme adjusts to the value of 'background' this will work. However, if the color scheme sets 'background' itself the effect may be undone.

So what actually happens when the 'background' option is changed is this:

If no colour scheme is currently loaded

Vim reloads the default colours, using foreground colours deemed appropriate for the new setting of 'background'

If a colour scheme is currently loaded

Vim reloads the colour scheme. When the colour scheme is loaded, either the colour scheme sets colours appropriate to the new setting of 'background', or the colour scheme resets 'background' to the old value.

As you have already described, the 'background' option is not intended to set the background, but instead to inform Vim whether the background is dark or light.

So if the colour scheme resets 'background', Vim takes this to mean that the colour scheme simply doesn't support the new setting of 'background'. Since the user has indicated they are using such a background this means that the current colour scheme is no longer appropriate, and so Vim unsets g:colors_name and then reloads the default colours.

If you'd like to explore the actual code that is run when 'background' is set, you can start here.

What's happening in your installation

The odd behaviour you describe (in the first version of your question) can be explained by this line in the documentation quoted above:

When a color scheme is loaded (the "g:colors_name" variable is set)

The problem is that your colors/darcula.vim file doesn't set this value, and so even though the colors changed when you invoked :color darcula, Vim doesn't consider a colour scheme to currently be loaded.

Therefore, when you call :set background=dark Vim carries out the step in the "If no colour scheme is currently loaded" section above, and sets the default colours for a dark background. This explains why :color then reports default.

(Note, however, that setting the default colours does not, as you might expect, remove all the colours that had previously been set, and this is why you end up with the results you see, rather than the colours that are displayed when you start up Vim in the first place. There's some discussion of this issue here. Edit: This issue was fixed in Vim 8.2.1693.)

In short, your colour scheme is misconfigured: See :edit $VIMRUNTIME/colors/README.txt (in particular the section at the bottom) for more details on this, and on the interaction between 'background' and colour schemes.

Answer 2

The doc at :h 'background' should provide all the information you need:

When set to "dark", Vim will try to use colors that look good on a dark background. When set to "light", Vim will try to use colors that look good on a light background. Any other value is illegal.

Your colorscheme defines 2 groups of colors: the ones used on a light background and the ones used on a dark background. The background option will tell vim which group of colors defined by your colorscheme should be used.

Setting this option does not change the background color, it tells Vim what the background color looks like. For changing the background color, see :h :hi-normal.

When 'background' is set Vim will adjust the default color groups for the new value. But the colors used for syntax highlighting will not change.

That's the follow up of the previous paragraph: It's the colorscheme which defines the groups of colors and background selects one of these groups.

Finally if you want to write your own color scheme without having to put set background=dark in your vimrc, remember that a colorscheme is nothing more than a program in vimscript, so nothing stops you from using the command directly in the code of your colorscheme like e.g. jellybeans or apprentice

Answer 3

Vim is just using you term colors, if you configure something on darkyellow vim will change it to yellow when you change the background mode.

All the colors codes are:

*cterm-colors*

NR-16   NR-8    COLOR NAME 
0       0       Black
1       4       DarkBlue
2       2       DarkGreen
3       6       DarkCyan
4       1       DarkRed
5       5       DarkMagenta
6       3       Brown, DarkYellow
7       7       LightGray, LightGrey, Gray, Grey
8       0*      DarkGray, DarkGrey
9       4*      Blue, LightBlue
10      2*      Green, LightGreen
11      6*      Cyan, LightCyan
12      1*      Red, LightRed
13      5*      Magenta, LightMagenta
14      3*      Yellow, LightYellow
15      7*      White

If you use an RGB code to configure there will be no change. So prefer to use a maximum term color.

An example with my .vimrc in dark mode or light mode and my term colors

Answer 4

Setting 'background' adjusts the default colors for the UI highlight groups (*highlight-groups*), and resets the standard syntax highlight groups (*group-name*) to the default colors for the set background, and thus it must be set before syntax highlighting commands to prevent overriding. If it isn't set explicitly in .vimrc, or in a separate colorscheme file loaded at startup, vim sets it itself by querying the background color. The valid values are 'light' and 'dark'.