vcs(3)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

NAME

vcs - MicroEmacs VCS interface - VCS-agnostic front-end
vcs-id - MicroEmacs VCS interface - identify the VCS controlling a file/directory
vcs-add - MicroEmacs VCS interface - add items
vcs-annotate - MicroEmacs VCS interface - annotate a file
vcs-blame - MicroEmacs VCS interface - annotate a file
vcs-checkout - MicroEmacs VCS interface - checkout (create) a working copy
vcs-coci - MicroEmacs VCS interface - check-out/check-in a file
vcs-commit - MicroEmacs VCS interface - commit changes to repository
vcs-commit-log - MicroEmacs VCS interface - get log for a commit
vcs-delete - MicroEmacs VCS interface - delete/remove items
vcs-diff - MicroEmacs VCS interface - diff changes
vcs-fetch - MicroEmacs VCS interface - download from another repository
vcs-gdiff - MicroEmacs VCS interface - graphical diff changes
vcs-log - MicroEmacs VCS interface - list log of changes
vcs-move - MicroEmacs VCS interface - move an item
vcs-pull - MicroEmacs VCS interface - download and integrate another repository
vcs-push - MicroEmacs VCS interface - update remote repository
vcs-remove - MicroEmacs VCS interface - remove items
vcs-revert - MicroEmacs VCS interface - revert local changes
vcs-setup - MicroEmacs VCS interface - setup the underlying VCS
vcs-status - MicroEmacs VCS interface - status of items
vcs-switch - MicroEmacs VCS interface - switch or create branches
vcs-unstage - MicroEmacs VCS interface - unstage items
vcs-update - MicroEmacs VCS interface - update directory files

SYNOPSIS

n vcs

n vcs-id [ "file-path" ]

vcs-add
vcs-annotate
vcs-blame
vcs-checkout
vcs-coci
vcs-commit
vcs-commit-log
vcs-delete
vcs-diff
vcs-fetch
vcs-gdiff
vcs-log
vcs-move
vcs-pull
vcs-push
vcs-remove
vcs-revert
vcs-setup
vcs-status
vcs-switch
vcs-unstage
vcs-update

DESCRIPTION

The vcs and sub-commands provide a VCS-agnostic front-end over MicroEmacs's individual version control system interfaces. Each command determines which VCS controls the current buffer's file (or the current directory) by calling vcs-id, and then forwards the request to the equivalent command of the underlying interface, i.e. vcs-status run against a file in a git(3) working copy executes git-status, in a svn(3) working copy executes svn-status, and so on. This allows a single set of key-bindings and menu entries to be used regardless of which VCS happens to control the file being edited.

This page only describes the behaviour common to vcs and its sub-commands; each command's action, its prompts and its options are ultimately those of the underlying VCS command it forwards to, so see git(3), svn(3), cvs(3) and ClearCase(3) for the details, dialogs and command-line options specific to that system.

Not every sub-command is implemented by every VCS interface; where this is the case it is noted below. If a sub-command is run against a VCS that does not implement it, an ml-write(2) message of the form [VCS Error: <vcs> does not support <action>] is reported and the command is abandoned. Similarly, a few pairs of sub-commands are simply synonyms of one another (e.g. vcs-blame/vcs-annotate) because the underlying VCS interfaces themselves use different names for the same action; these are noted below too.

The MicroEmacs vcs command itself opens the file-browser of the detected VCS, i.e. it is equivalent to running git(3), svn(3) or cvs(3) directly, including the same use of a numeric argument n of zero to open a single directory-only window (i.e. 0 vcs). Only supported by Git, SVN and CVS; ClearCase does not currently provide an equivalent browser entry point via vcs, use ClearCase(3) directly instead.

Identifying the VCS

vcs-id identifies which VCS (Git, SVN, CVS or ClearCase) controls a given file or directory, walking up the directory tree as necessary to locate a .git, .svn or CVS control directory, or, for ClearCase, a matching view record. The result of the last two lookups is cached so that repeated calls for files in the same directory are cheap.

All of the vcs-* sub-commands described below use vcs-id internally to select which <vcs>-<command> macro to forward to, and it is also used by the file-browser's directory-listing file-hook to select the appropriate VCS state format for a directory listing, see file-browser(3).

vcs-id optionally takes a file or directory path as its argument; if omitted the current buffer's file name is used. When called with a numeric argument (as it is internally by the other vcs-* commands and by the file-browser hook) it operates silently, only setting up its result for the calling macro. When run directly by the user with no numeric argument it instead reports the identified VCS on the message line, e.g. VCS for "<file>" is Git (git). If no controlling VCS can be identified for the given file or directory an error is reported and the command is abandoned.

Sub-Commands

The vcs-add command adds the current buffer or selected items to the VCS.

The vcs-annotate command is a synonym for vcs-blame.

The vcs-blame command opens a window annotating each line of the current buffer or a single selected file with the revision/commit and author that last changed it.

The vcs-checkout command checks out (creates) a working copy from the repository. Only supported by SVN, CVS and ClearCase; Git users should use vcs-switch to change branches, or vcs-revert/vcs-unstage to discard local file changes.

The vcs-coci command performs a simple RCS-style check-out/check-in of the current buffer's file, see rcs-file(2). Of the supported VCS systems only ClearCase has this per-file check-out/check-in concept (Git, SVN and CVS have no equivalent lock/checkout model), toggling between checking the file out and checking it back in depending on the buffer's current view(2m) mode state; only supported by ClearCase. If the file is not controlled by any of Git, SVN, CVS or ClearCase then rcs-file(2) is invoked directly instead, giving equivalent behaviour on a standalone file kept under plain $rcs-file(5) control. Directories are not supported by either form of this command.

The vcs-commit command commits changes made to the current buffer's file or selection back to the repository, the user typically being prompted for a commit log message; exactly what gets committed (e.g. the index/staging area for Git, or the working copy directly for SVN/CVS) depends on the underlying VCS. Not currently supported for ClearCase, use ClearCase(3)'s own check-in command instead.

The vcs-commit-log command displays the log message and affected files of a specific commit. Only supported by SVN at present.

The vcs-delete command removes the current buffer or selected items from VCS control, and typically the local file too - PLEASE NOTE THIS CAN LEAD TO LOST DATA!!! vcs-remove is a synonym for this command.

The vcs-diff command displays the differences between the current buffer or selected local files and the repository version.

The vcs-fetch command downloads changes from a remote repository without altering the local files or index. Only supported by Git at present.

The vcs-gdiff command launches a graphical diff to display changes. Only supported by CVS at present, for other systems see %xdiff-com(5) based commands such as svn-xdiff.

The vcs-log command displays the commit/revision log history of the current buffer or selected files. Not currently supported for ClearCase.

The vcs-move command moves (renames) the current buffer's file or selected items, preserving the item's change log history where the underlying VCS supports this. Not currently supported for CVS.

The vcs-pull command is a synonym for vcs-update.

The vcs-push command updates the remote repository with committed local changes. Only supported by Git at present.

The vcs-remove command is a synonym for vcs-delete.

The vcs-revert command reverts local modifications back to the repository version, discarding the local changes. Currently only supported by Git and SVN, not CVS or ClearCase.

The vcs-setup command opens the setup dialog of the current buffer's underlying VCS interface, e.g. git(3)'s git-setup; it does not have any configuration of its own, each underlying interface must be set up individually.

The vcs-status command opens a window showing the state of all the items within the current directory. Not currently mapped for ClearCase, which names its equivalent command cc-state, see ClearCase(3).

The vcs-switch command switches to an existing branch, or creates and switches to a new one. Only supported by Git at present; SVN, CVS and ClearCase have no equivalent branch-switching concept for this command to forward to.

The vcs-unstage command removes items from the staging area/index without discarding the underlying local modifications. Only supported by Git at present.

The vcs-update command updates the local working files with changes from the repository. vcs-pull is a synonym for this command.

NOTES

vcs and sub-commands are macros defined in file vcs.emf. They are a thin dispatch layer only; the underlying VCS interface (git.emf, svn.emf, cvs.emf or cc.emf) for a given file's VCS must be set up correctly, e.g. via git-setup, svn-setup, cvs-setup or cc-setup, for its vcs-* commands to function.