CLI options

This chapter discusses some of the options you can use when starting Vim from the command line. A Unix/Linux distribution is assumed for the examples shown in this chapter. Syntax and features might vary for other platforms like Windows.

Documentation links:

• :h vim-arguments — reference manual for Vim arguments

Recall that you need to add - prefix for built-in help on CLI options, :h -y for example.

Default

• gvim opens a new unnamed buffer when a filename is not specified
• gvim script.py opens script.py
  • creates a blank buffer if script.py doesn't exist, file will be created only after you explicitly issue write commands
• gvim report.log power.log area.log opens the specified files
  • first file (report.log here) will be the current buffer
• gvim -- *.txt if filenames can start with -, use -- to prevent such files from being treated as an option

Help

• gvim -h brief description of the options
  • not all options are discussed in this chapter, so you can use this to view the full list

Tabs and Splits

• gvim -p *.log opens the specified files as separate tab pages
  • by default, you can open a maximum of 10 pages, use the tabpagemax setting if you want to change this number
• gvim -o *.log opens the specified files as horizontal splits
• gvim -O *.log opens the specified files as vertical splits

You can append a number to each of these options to specify how many tabs or splits you want. For example, gvim -p3 *.py opens three tabs irrespective of the number of input files. Empty buffers will be used if there aren't enough input files to satisfy the given number.

Easy mode

• gvim -y opens in Insert mode and behaves like a click-and-type editor
  • useful for those who just want a simple text editor
  • or, perhaps you can prank Vim users by setting alias vim='vim -y'
  • use Ctrl+l or Ctrl+o if you want to use Normal mode commands

See also novim-mode plugin, which aims to make Vim behave more like a normal editor.

Readonly and Restricted modes

• gvim -R Readonly mode
  • changes can still be made and saved despite warning messages
  • for example, by using :w!
• gvim -M stricter Readonly mode
  • changes cannot be made unless :set modifiable is used
  • file cannot be saved until :set write is used
• gvim -Z Restricted mode
  • commands using external shell are not allowed
  • for example, you won't be able to use :!ls

Cursor position

• gvim + script.py opens script.py and the cursor is placed on the last line
• gvim +25 script.py opens script.py and the cursor is placed on the 25th line
  • if the number goes beyond the available lines in the file, the cursor will be placed on the last line
• gvim +/while script.py opens script.py and the cursor is placed on the first line containing the given pattern
  • if the pattern is not found, the cursor will be placed on the last line
  • use gvim +1 +/pattern to force the search to start from the first line, otherwise cursor position stored in viminfo will be used (if applicable)

Execute command

• gvim -c allows you to execute the Command-line mode command passed as an argument
• gvim -c '%s/search/replace/g' script.py opens script.py and performs the given substitute operation
• gvim -c 'normal =G' script.py opens script.py and auto indents the entire file content

As per :h -c, "You can use up to 10 + or -c arguments in a Vim command. They are executed in the order given. A -S argument counts as a -c argument as well"

--cmd option is similar to the -c option, but executes the command before loading any vimrc files.

Quickfix

• gvim -q <(grep -Hn 'search' *.py) interactively edit the matching lines from grep output
  • -H and -n options provide filename and line number prefix for the matching lines
  • use :cn and :cp to navigate to the next and previous occurrences respectively
  • Command-line area at the bottom will show the number of matches and filenames
  • you can also use gvim -q file if you had saved the grep output to that file
• gvim -q error.log edit source code based on compiler output containing filenames and line numbers for the error locations
  • here, the error.log is assumed to be the filename used to save the error messages

See Vim and the quickfix list and stackoverflow: How do you use Vim's quickfix feature? to learn more about this feature.

See :h quickfix for documentation.

Vimrc and Plugins

• gvim -u file uses the given file for initialization instead of vimrc files
  • useful to test plugins, apply a different vimrc based on which project you are working on, etc
• gvim -u NONE all initializations are skipped
• gvim -u DEFAULTS similar to NONE, but defaults.vim is loaded
• gvim -u NORC similar to NONE, but plugins are loaded
• gvim --noplugin only plugins are not loaded

Here's a neat table from :h --noplugin:

Session and Viminfo

• gvim -S proj.vim restore a session using the previously saved session file
  • see :h Session for more details
• gvim -i proj.viminfo restore Viminfo from the given file
  • this file will also be used instead of the default viminfo file to save information
  • see :h viminfo-read-write for more details