---

30.1.3.1 Basic Version Control with Merging ¶

With a modern merging-based version control system (such as Git and Hg; see Merge-based vs Lock-based Version Control), C-x v v does the following when invoked from a buffer that visits a version-controlled file or a VC Directory or Dired buffer:

• If there is more than one file in the VC fileset and the files have inconsistent version control statuses, signal an error. (Note, however, that a fileset is allowed to include both newly-added files, removed files and modified files; see Registering a File for Version Control.) Also signal an error if any files in the fileset are ignored by version control.
• If every file in the VC fileset is registered and unchanged with respect to the last revision, do nothing.
• If none of the files in the VC fileset are registered with a version control system, register the newly-added files in the VC fileset, i.e., place them under version control. See Registering a File for Version Control. If Emacs cannot find a system to register under, it prompts for a repository type, creates a new repository, and registers the VC fileset with it. You can also specify the system explicitly, see Advanced Control in C-x v v. Note that registering the files doesn’t commit them; you must invoke C-x v v again to commit; see the next point.
• If every file in the VC fileset has been either newly-added or modified, commit the changed files. To do this, Emacs pops up a *vc-log* buffer; type the desired log entry for the changes, followed by C-c C-c to commit. See Features of the Log Entry Buffer.

  If C-x v v is invoked from a buffer under Diff mode, the command treats the buffer as holding a set of patches for one or more files. It then applies the changes to the respective files and commits the changes after popping up the *vc-log* buffer to allow you to type a suitable commit log message.

  Once you type C-x v v, the fileset or patches cannot be changed without first canceling the commit by typing C-c C-k in the *vc-log* buffer. For example, if you change which files are marked in the *vc-dir* buffer after Emacs has already popped up the *vc-log* buffer, the old fileset will remain in effect for this commit. (This is in contrast to changes made to the contents of files in the fileset when not committing patches: all such changes will be included in the commit even if they are made after Emacs has popped up the *vc-log* buffer.)

  When you cancel a commit, Emacs saves your log message. This means that if you need to adjust the fileset or patches, it is easy to restart the commit operation again: type C-c C-k C-x v v M-p. Here C-c C-k cancels the commit, C-x v v initiates another with the new fileset or patches, and finally M-p recalls your previous log message.

  With modern decentralized version control systems (Git, Mercurial, etc.), the changes are committed locally and not automatically propagated to the upstream repository (which is usually on a remote host). In these cases, if the repository has been changed since your last update, the commit may fail. In that case, you must update from upstream and then try again. Use C-x v + (see Pulling/Pushing Changes into/from a Branch) or C-x v m (see Merging Branches) for that.

  With a centralized version control system, if the commit fails due to upstream changes, type C-x v v again to merge in the upstream repository changes.

• Finally, if you are using a centralized version control system, if any file in the VC fileset is outdated with respect to the upstream repository, offer to update the fileset from the repository.

These rules also apply when you use RCS in its non-locking mode, except that changes are not automatically merged from the repository. Nothing informs you if another user has committed changes in the same file since you began editing it; when you commit your revision, that other user’s changes are removed (however, they remain in the repository and are thus not irrevocably lost). Therefore, you must verify that the current revision is unchanged before committing your changes. In addition, locking is possible with RCS even in this mode: C-x v v with an unmodified file locks the file, just as it does with RCS in its normal locking mode (see Basic Version Control with Locking).