30.1.5 Registering a File for Version Control

C-x v i

Register the visited file for version control.

The command C-x v i (vc-register) registers each file in the current VC fileset, placing it under version control. This is essentially equivalent to the action of C-x v v on an unregistered VC fileset (see Basic Editing under Version Control), except that if the VC fileset is already registered, C-x v i signals an error whereas C-x v v performs some other action.

To register a file, Emacs must choose a version control system. For a multi-file VC fileset, the VC Directory buffer specifies the system to use (see VC Directory Mode). For a single-file VC fileset, if the file’s directory already contains files registered in a version control system, or if the directory is part of a directory tree controlled by a version control system, Emacs chooses that system. In the event that more than one version control system is applicable, Emacs uses the one that appears first in the variable vc-handled-backends (see Customizing VC). If Emacs cannot find a version control system to register the file under, it prompts for a repository type, creates a new repository, and registers the file into that repository.

With most version control systems, registering a file with C-x v i or C-x v v adds it to the working tree, but does not commit it, i.e., doesn’t add it to the repository. Such files are labeled as added in the VC Directory buffer, and the mode line of the buffers visiting such files shows a revision ID of ‘@@’. To make the registration take effect in the repository, you must commit the newly-added files (see Basic Editing under Version Control). Note that a single commit can include both file additions and edits to files already known to the VCS.

With a locking-based version control system (see Merge-based vs Lock-based Version Control), registering a file leaves it unlocked and read-only. Type C-x v v to check-out the file and start editing it.