Now on revision 106705. ------------------------------------------------------------ revno: 106705 committer: martin rudalics branch nick: trunk timestamp: Tue 2011-12-20 08:45:20 +0100 message: Restore Emacs 23 handling of display-buffer's BUFFER-OR-NAME argument. * window.el (window-normalize-buffer-to-display): Remove. (display-buffer): Handle buffer-or-name argument as in Emacs 23. diff: === modified file 'lisp/ChangeLog' --- lisp/ChangeLog 2011-12-19 15:46:50 +0000 +++ lisp/ChangeLog 2011-12-20 07:45:20 +0000 @@ -1,3 +1,8 @@ +2011-12-20 Martin Rudalics + + * window.el (window-normalize-buffer-to-display): Remove. + (display-buffer): Handle buffer-or-name argument as in Emacs 23. + 2011-12-19 Chong Yidong * vc/vc-dir.el (vc-dir-parent-marked-p, vc-dir-children-marked-p): === modified file 'lisp/window.el' --- lisp/window.el 2011-12-17 06:51:13 +0000 +++ lisp/window.el 2011-12-20 07:45:20 +0000 @@ -4526,19 +4526,6 @@ The actual non-nil value of this variable will be copied to the `window-dedicated-p' flag.") -(defun window-normalize-buffer-to-display (buffer-or-name) - "Normalize BUFFER-OR-NAME argument for buffer display functions. -If BUFFER-OR-NAME is nil, return the current buffer. Else, if a -buffer specified by BUFFER-OR-NAME exists, return that buffer. -If no such buffer exists, create a buffer with the name -BUFFER-OR-NAME and return that buffer." - (if buffer-or-name - (or (get-buffer buffer-or-name) - (let ((buffer (get-buffer-create buffer-or-name))) - (set-buffer-major-mode buffer) - buffer)) - (current-buffer))) - (defconst display-buffer--action-function-custom-type '(choice :tag "Function" (const :tag "--" ignore) ; default for insertion @@ -4640,7 +4627,7 @@ "A `display-buffer' action for displaying in another frame.") (put 'display-buffer--other-frame-action 'risky-local-variable t) -(defun display-buffer (&optional buffer-or-name action frame) +(defun display-buffer (buffer-or-name &optional action frame) "Display BUFFER-OR-NAME in some window, without selecting it. BUFFER-OR-NAME must be a buffer or the name of an existing buffer. Return the window chosen for displaying BUFFER-OR-NAME, @@ -4688,7 +4675,9 @@ `display-buffer-reuse-window'." (interactive (list (read-buffer "Display buffer: " (other-buffer)) (if current-prefix-arg t))) - (let ((buffer (window-normalize-buffer-to-display buffer-or-name)) + (let ((buffer (if (bufferp buffer-or-name) + buffer-or-name + (get-buffer buffer-or-name))) ;; Handle the old form of the first argument. (inhibit-same-window (and action (not (listp action))))) (unless (listp action) (setq action nil)) ------------------------------------------------------------ revno: 106704 committer: Chong Yidong branch nick: trunk timestamp: Tue 2011-12-20 11:00:10 +0800 message: More updates for VC documentation. * doc/emacs/maintaining.texi (VCS Concepts): Add "working tree" terminology. (Old Revisions): Use it. (VCS Repositories): Add "distributed" terminology. (Log Buffer): Remove duplicate description about changesets. Fix "current VC fileset" ambiguity. (Multi-User Branching): Node deleted. (Branches, Switching Branches): Discuss decentralized version control systems. (VC Pull): New node. (Merging): Document merging on decentralized systems. (Creating Branches): Note that this is specific to CVS and related systems. diff: === modified file 'doc/emacs/ChangeLog' --- doc/emacs/ChangeLog 2011-12-19 07:25:46 +0000 +++ doc/emacs/ChangeLog 2011-12-20 03:00:10 +0000 @@ -1,3 +1,18 @@ +2011-12-20 Chong Yidong + + * maintaining.texi (VCS Concepts): Add "working tree" terminology. + (Old Revisions): Use it. + (VCS Repositories): Add "distributed" terminology. + (Log Buffer): Remove duplicate description + about changesets. Fix "current VC fileset" ambiguity. + (Multi-User Branching): Node deleted. + (Branches, Switching Branches): Discuss decentralized version + control systems. + (VC Pull): New node. + (Merging): Document merging on decentralized systems. + (Creating Branches): Note that this is specific to CVS and related + systems. + 2011-12-19 Chong Yidong * maintaining.texi (VCS Merging, VCS Changesets): Index entries. === modified file 'doc/emacs/emacs.texi' --- doc/emacs/emacs.texi 2011-12-17 07:50:08 +0000 +++ doc/emacs/emacs.texi 2011-12-20 03:00:10 +0000 @@ -776,10 +776,9 @@ Multiple Branches of a File * Switching Branches:: How to get to another existing branch. +* VC Pull:: Updating a branch from another branch. +* Merging:: Transferring changes between branches. * Creating Branches:: How to start a new branch. -* Merging:: Transferring changes between branches. -* Multi-User Branching:: Multiple users working at multiple branches - in parallel. Remote Repositories === modified file 'doc/emacs/maintaining.texi' --- doc/emacs/maintaining.texi 2011-12-19 07:25:46 +0000 +++ doc/emacs/maintaining.texi 2011-12-20 03:00:10 +0000 @@ -164,14 +164,14 @@ @cindex GNU Arch @cindex Arch @item -GNU Arch is one of the earliest @dfn{distributed} version control +GNU Arch is one of the earliest @dfn{decentralized} version control systems (the other being Monotone). @xref{VCS Concepts}, for a -description of distributed version control systems. It is no longer +description of decentralized version control systems. It is no longer under active development, and has been deprecated in favor of Bazaar. @cindex git @item -Git is a distributed version control system originally invented by +Git is a decentralized version control system originally invented by Linus Torvalds to support development of Linux (his kernel). VC supports many common Git operations, but others, such as repository syncing, must be done from the command line. @@ -179,15 +179,15 @@ @cindex hg @cindex Mercurial @item -Mercurial (hg) is a distributed version control system broadly +Mercurial (hg) is a decentralized version control system broadly resembling Git. VC supports most Mercurial commands, with the exception of repository sync operations. @cindex bzr @cindex Bazaar @item -Bazaar (bzr) is a distributed version control system that supports -both repository-based and distributed versioning. VC supports most +Bazaar (bzr) is a decentralized version control system that supports +both repository-based and decentralized versioning. VC supports most basic editing operations under Bazaar. @end itemize @@ -211,6 +211,9 @@ may @dfn{commit} (or @dfn{check in}) the changes; this records the changes in the repository, along with a descriptive log entry. +@cindex working tree + A directory tree of work files is called a @dfn{working tree}. + @cindex revision @cindex revision ID Each commit creates a new @dfn{revision} in the repository. The @@ -263,7 +266,7 @@ SCCS always uses locking. RCS is lock-based by default but can be told to operate in a merging style. CVS and Subversion are merge-based by default but can be told to operate in a locking mode. -Distributed version control systems, such as GNU Arch, Git, and +Decentralized version control systems, such as GNU Arch, Git, and Mercurial, are exclusively merging-based. VC mode supports both locking and merging version control. The @@ -295,18 +298,20 @@ @cindex centralized version control @cindex decentralized version control +@cindex distributed version control Early version control systems were designed around a @dfn{centralized} model in which each project has only one repository used by all developers. SCCS, RCS, CVS, and Subversion share this kind of model. One of its drawbacks is that the repository is a choke point for reliability and efficiency. - GNU Arch pioneered the concept of @dfn{decentralized} version -control, later implemented in Git, Mercurial, and Bazaar. A project -may have several different repositories, and these systems support a -sort of super-merge between repositories that tries to reconcile their -change histories. In effect, there is one repository for each -developer, and repository merges take the place of commit operations. + GNU Arch pioneered the concept of @dfn{distributed} or +@dfn{decentralized} version control, later implemented in Git, +Mercurial, and Bazaar. A project may have several different +repositories, and these systems support a sort of super-merge between +repositories that tries to reconcile their change histories. In +effect, there is one repository for each developer, and repository +merges take the place of commit operations. VC helps you manage the traffic between your personal workfiles and a repository. Whether the repository is a single master, or one of a @@ -411,14 +416,13 @@ Directory buffer, and some files in it are marked, the VC fileset consists of the marked files (@pxref{VC Directory Mode}). - On Subversion and on decentralized version control systems, -multi-file VC filesets are handled as a single group by the relevant -version control commands. For example, committing a multi-file VC -fileset generates a single revision, consisting of all the changes to -those files. But on older version control systems which lack support -for group operations, such as CVS, the files in a multi-file VC -fileset are passed individually to version control commands (e.g.@: a -commit generates one revision for each changed file). + On modern changeset-based version control systems (@pxref{VCS +Changesets}), VC commands handle multi-file VC filesets as a group. +For example, committing a multi-file VC fileset generates a single +revision, containing the changes to all those files. On older +file-based version control systems like CVS, each file in a multi-file +VC fileset is handled individually; for example, a commit generates +one revision for each changed file. @table @kbd @itemx C-x v v @@ -428,7 +432,7 @@ @findex vc-next-action @kindex C-x v v - The principal VC command is an all-purpose command, @kbd{C-x v v} + The principal VC command is a multi-purpose command, @kbd{C-x v v} (@code{vc-next-action}), which performs the ``most appropriate'' action on the current VC fileset: either registering it with a version control system, or committing it, or unlocking it, or merging changes @@ -599,13 +603,13 @@ Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook} (@pxref{Hooks}). - While in the @samp{*vc-log*} buffer, you can write one or more -@dfn{header lines}, specifying additional information to be supplied -to the version control system. Each header line must occupy a single -line at the top of the buffer; the first line that is not a header -line is treated as the start of the log entry. For example, the -following header line states that the present change was not written -by you, but by another developer: + In the @samp{*vc-log*} buffer, you can write one or more @dfn{header +lines}, specifying additional information to be supplied to the +version control system. Each header line must occupy a single line at +the top of the buffer; the first line that is not a header line is +treated as the start of the log entry. For example, the following +header line states that the present change was not written by you, but +by another developer: @smallexample Author: J. R. Hacker @@ -617,32 +621,25 @@ reference to a bug fixed by the change). Not all version control systems recognize all headers: Bazaar recognizes all three headers, while Git, Mercurial, and Monotone recognize only @samp{Author} and -@samp{Date}. If you specify a header for a version control that does -not support it, the header is treated as part of the log entry. +@samp{Date}. If you specify a header for a system that does not +support it, the header is treated as part of the log entry. @kindex C-c C-f @r{(Log Edit mode)} @findex log-edit-show-files - Type @kbd{C-c C-f} (@code{log-edit-show-files}) in the -@samp{*vc-log*} buffer to view a list of files for the VC fileset that -is to be committed. If you called @kbd{C-x v v} directly from a work -file, the fileset consists of that single file. If you called -@kbd{C-x v v} from a VC directory buffer (@pxref{VC Directory Mode}), -the fileset may consist of multiple files; in that case, @kbd{C-c C-c} -will commit those files together, as a single revision, if that is -supported by the version control system (on older version control -systems, such as CVS, each file in a multi-file VC fileset is -committed as an individual revision). - @kindex C-c C-d @r{(Log Edit mode)} @findex log-edit-show-diff - Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a @dfn{diff} -of the changes between the current VC fileset and the repository -revision from which you started editing. @xref{Old Revisions}. + While in the @samp{*vc-log*} buffer, the ``current VC fileset'' is +considered to be the fileset that will be committed if you type +@w{@kbd{C-c C-c}}. To view a list of the files in the VC fileset, +type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}). To view a diff +of changes between the VC fileset and the version from which you +started editing (@pxref{Old Revisions}), type @kbd{C-c C-d} +(@code{log-edit-show-diff}). @kindex C-c C-a @r{(Log Edit mode)} @findex log-edit-insert-changelog - If the VC fileset that is to be committed includes one or more -@file{ChangeLog} files (@pxref{Change Log}), type @kbd{C-c C-a} + If the VC fileset includes one or more @file{ChangeLog} files +(@pxref{Change Log}), type @kbd{C-c C-a} (@code{log-edit-insert-changelog}) to pull the relevant entries into the @samp{*vc-log*} buffer. If the topmost item in each @file{ChangeLog} was made under your user name on the current date, @@ -650,7 +647,7 @@ committed, and inserts them. @ifnottex @xref{Change Logs and VC}, for the opposite way of -working---generating ChangeLog entries from the revision control log. +working---generating ChangeLog entries from the Log Edit buffer. @end ifnottex To abort a commit, just @strong{don't} type @kbd{C-c C-c} in that @@ -710,9 +707,8 @@ repository. Such files are labeled as @samp{added} in the VC Directory buffer, and show a revision ID of @samp{@@@@} in the mode line. To make the registration take effect in the repository, you -must perform a commit (@pxref{Basic VC Editing}). Note that on -changeset-based version control systems, commits can consist of both -file additions and modifications. +must perform a commit (@pxref{Basic VC Editing}). Note that a single +commit can include both file additions and edits to existing files. On a locking-based version control system (@pxref{VCS Merging}), registering a file leaves it unlocked and read-only. Type @kbd{C-x v @@ -730,14 +726,14 @@ @ifnottex @item M-x vc-ediff -Like @kbd{C-x v =}, but using an Ediff session. @xref{Top, Ediff, -ediff, The Ediff Manual}. +Like @kbd{C-x v =}, but using Ediff. @xref{Top, Ediff, ediff, The +Ediff Manual}. @end ifnottex @item C-x v D -Compare all work files in the current version controlled directory -tree to the tree you started from (@code{vc-root-diff}). With a -prefix argument, prompt for two revisions and compare their trees. +Compare the entire working tree to the revision you started from +(@code{vc-root-diff}). With a prefix argument, prompt for two +revisions and compare their trees. @item C-x v ~ Prompt for a revision of the current file, and visit it in a separate @@ -788,12 +784,10 @@ @findex vc-root-diff @kindex C-x v D @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but -it displays a comparison between the entire current version controlled -tree (i.e.@: the tree controlled by the version control system -associated with the current VC fileset, which may include files that -are not part of that fileset) and the tree you started with. If you -invoke this command from a Dired buffer, it applies to the entire -version controlled tree containing the directory. +it displays the changes in the entire current working tree (i.e.@: the +working tree containing the current VC fileset). If you invoke this +command from a Dired buffer, it applies to the working tree containing +the directory. @vindex vc-diff-switches You can customize the @command{diff} options that @kbd{C-x v =} and @@ -801,14 +795,14 @@ from the first non-@code{nil} value amongst the variables @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and @code{diff-switches} (@pxref{Comparing Files}), in that order. Here, -@var{backend} stands for the current version control system, +@var{backend} stands for the relevant version control system, e.g.@: @code{bzr} for Bazaar. Since @code{nil} means to check the next variable in the sequence, either of the first two may use the value @code{t} to mean no switches at all. Most of the @code{vc-@var{backend}-diff-switches} variables default to @code{nil}, -but some default to @code{t}; these are for version control systems, -such as Subversion, whose @code{diff} implementations do not accept -common diff options. +but some default to @code{t}; these are for version control systems +whose @code{diff} implementations do not accept common diff options, +such as Subversion. @findex vc-revision-other-window @kindex C-x v ~ @@ -937,7 +931,7 @@ @samp{*vc-change-log*} buffer to reveal the entire log entry for the revision at point. A second @key{RET} hides it again. - On a distributed version control system, the @kbd{C-x v I} + On a decentralized version control system, the @kbd{C-x v I} (@code{vc-log-incoming}) command displays a log buffer showing the changes that will be applied, the next time you run the version control system's ``pull'' command to get new revisions from another @@ -1144,9 +1138,8 @@ @vindex vc-directory-exclusion-list The VC Directory buffer omits subdirectories listed in the variable -@code{vc-directory-exclusion-list}. The default value of this -variable contains directories that are used internally by version -control systems. +@code{vc-directory-exclusion-list}. Its default value contains +directories that are used internally by version control systems. @node VC Directory Commands @subsubsection VC Directory Commands @@ -1268,221 +1261,174 @@ bring them back at a later time). @node Branches -@subsection Multiple Branches of a File +@subsection Version Control Branches @cindex branch (version control) -@cindex trunk (version control) - - One use of version control is to maintain multiple ``current'' -revisions of a file. For example, you might have different revisions of a -program in which you are gradually adding various unfinished new -features. Each such independent line of development is called a -@dfn{branch}. VC allows you to create branches, switch between -different branches, and merge changes from one branch to another. -Please note, however, that branches are not supported for SCCS. - - A file's main line of development is usually called the @dfn{trunk}. -You can create multiple branches from the trunk. How the difference -between trunk and branch is made visible is dependent on whether the -VCS uses dot-pair or monotonic version IDs. - - In VCSes with dot-pair revision IDs, the revisions on the trunk are -normally IDed 1.1, 1.2, 1.3, etc. At any such revision, you can -start an independent branch. A branch starting at revision 1.2 would -have revision ID 1.2.1.1, and consecutive revisions on this branch -would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is -a second branch also starting at revision 1.2, it would consist of -revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. - - In VCSes with monotonic revision IDs, trunk revisions are IDed as -1, 2, 3, etc. A branch from (say) revision 2 might start with 2.1 and -continue through 2.2, 2.3, etc. But naming conventions for branches -and subbranches vary widely on these systems, and some (like -Mercurial) never depart from the monotonic integer sequence at all. -Consult the documentation of the VCS you are using. - -@cindex head revision - If you omit the final component of a dot-pair revision ID, that is called a -@dfn{branch ID}. It refers to the highest existing revision on that -branch---the @dfn{head revision} of that branch. The branches in the -dot-pair example above have branch IDs 1.2.1 and 1.2.2. + + One use of version control is to support multiple independent lines +of development, which are called @dfn{branches}. Branches are used +for maintaining separate ``stable'' and ``development'' versions of a +program, and for developing unrelated features in isolation from one +another. + + VC's support for branch operations is currently fairly limited. For +decentralized version control systems, it provides commands for +@dfn{updating} one branch with the contents of another, and for +@dfn{merging} the changes made to two different branches +(@pxref{Merging}). For centralized version control systems, it +supports checking out different branches and committing into new or +different branches. @menu * Switching Branches:: How to get to another existing branch. +* VC Pull:: Updating the contents of a branch. +* Merging:: Transferring changes between branches. * Creating Branches:: How to start a new branch. -* Merging:: Transferring changes between branches. -* Multi-User Branching:: Multiple users working at multiple branches - in parallel. @end menu @node Switching Branches @subsubsection Switching between Branches - To switch between branches, type @kbd{C-u C-x v v} and specify the -revision ID you want to select. On a locking-based system, this -version is then visited @emph{unlocked} (write-protected), so you can -examine it before locking it. Switching branches in this way is allowed -only when the file is not locked. - - On a VCS with dot-pair IDs, you can omit the minor part, thus giving -only the branch ID; this takes you to the head version on the -chosen branch. If you only type @key{RET}, Emacs goes to the highest -version on the trunk. - - After you have switched to any branch (including the main branch), you -stay on it for subsequent VC commands, until you explicitly select some -other branch. + The various version control systems differ in how branches are +implemented, and these differences cannot be entirely concealed by VC. + + On some decentralized version control systems, including Bazaar and +Mercurial in its normal mode of operation, each branch has its own +working directory tree, so switching between branches just involves +switching directories. On Git, switching between branches is done +using the @command{git branch} command, which changes the contents of +the working tree itself. + + On centralized version control systems, you can switch between +branches by typing @kbd{C-u C-x v v} in an up-to-date work file +(@pxref{Advanced C-x v v}), and entering the revision ID for a +revision on another branch. On CVS, for instance, revisions on the +@dfn{trunk} (the main line of development) normally have IDs of the +form 1.1, 1.2, 1.3, @dots{}, while the first branch created from (say) +revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, @dots{}, the second +branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2, +@dots{}, and so forth. You can also specify the @dfn{branch ID}, +which is a branch revision ID omitting its final component +(e.g.@: 1.2.1), to switch to the latest revision on that branch. + + On a locking-based system, switching to a different branch also +unlocks (write-protects) the working tree. + + Once you have switched to a branch, VC commands will apply to that +branch until you switch away; for instance, any VC filesets that you +commit will be committed to that specific branch. + +@node VC Pull +@subsubsection Pulling Changes into a Branch + +@table @kbd +@itemx C-x v + +On a decentralized version control system, update the current branch +by ``pulling in'' changes from another location. + +On a centralized version control system, update the current VC +fileset. +@end table + +@kindex C-x v + +@findex vc-pull + On a decentralized version control system, the command @kbd{C-x v +} +(@code{vc-pull}) updates the current branch and working tree. It is +typically used to update a copy of a remote branch. If you supply a +prefix argument, the command prompts for the exact version control +command to use, which lets you specify where to pull changes from. +Otherwise, it pulls from a default location determined by the version +control system. + + Amongst decentralized version control systems, @kbd{C-x v +} +currently supports only Bazaar, Git, and Mercurial. On Bazaar, it +calls @command{bzr pull} for ordinary branches (to pull from a master +branch into a mirroring branch), and @command{bzr update} for a bound +branch (to pull from a central repository). On Git, it calls +@command{git pull} to fetch changes from a remote repository and merge +it into the current branch. On Mercurial, it calls @command{hg pull +-u} to fetch changesets from the default remote repository and update +the working directory. + + On a centralized version control system like CVS, @kbd{C-x v +} +updates the current VC fileset from the repository. + +@node Merging +@subsubsection Merging Branches +@cindex merging changes + +@table @kbd +@itemx C-x v m +On a decentralized version control system, merge changes from another +branch into the current one. + +On a centralized version control system, merge changes from another +branch into the current VC fileset. +@end table + + While developing a branch, you may sometimes need to @dfn{merge} in +changes that have already been made in another branch. This is not a +trivial operation, as overlapping changes may have been made to the +two branches. + + On a decentralized version control system, merging is done with the +command @kbd{C-x v m} (@code{vc-merge}). On Bazaar, this prompts for +the exact arguments to pass to @command{bzr merge}, offering a +sensible default if possible. On Git, this prompts for the name of a +branch to merge from, with completion (based on the branch names known +to the current repository). The output from running the merge command +is shown in a separate buffer. + + On a centralized version control system like CVS, @kbd{C-x v m} +prompts for a branch ID, or a pair of revision IDs (@pxref{Switching +Branches}); then it finds the changes from that branch, or the changes +between the two revisions you specified, and merges those changes into +the current VC fileset. If you just type @key{RET}, Emacs simply +merges any changes that were made on the same branch since you checked +the file out. + +@cindex conflicts +@cindex resolving conflicts + Immediately after performing a merge, only the working tree is +modified, and you can review the changes produced by the merge with +@kbd{C-x v D} and related commands (@pxref{Old Revisions}). If the +two branches contained overlapping changes, merging produces a +@dfn{conflict}; a warning appears in the output of the merge command, +and @dfn{conflict markers} are inserted into each affected work file, +surrounding the two sets of conflicting changes. You must then +resolve the conflict by editing the conflicted files. Once you are +done, the modified files must be committed in the usual way for the +merge to take effect (@pxref{Basic VC Editing}). @node Creating Branches @subsubsection Creating New Branches - To create a new branch from a head revision (one that is the latest -in the branch that contains it), first select that revision if -necessary, lock it with @kbd{C-x v v}, and make whatever changes you -want. Then, when you commit the changes, use @kbd{C-u C-x v v}. This -lets you specify the revision ID for the new revision. You should -specify a suitable branch ID for a branch starting at the current -revision. For example, if the current revision is 2.5, the branch ID -should be 2.5.1, 2.5.2, and so on, depending on the number of existing -branches at that point. + On centralized version control systems like CVS, Emacs supports +creating new branches as part of a commit operation. When committing +a modified VC fileset, type @kbd{C-u C-x v v} (@code{vc-next-action} +with a prefix argument; @pxref{Advanced C-x v v}). Then Emacs prompts +for a revision ID for the new revision. You should specify a suitable +branch ID for a branch starting at the current revision. For example, +if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2, +and so on, depending on the number of existing branches at that point. - To create a new branch at an older revision (one that is no longer the -head of a branch), first select that revision (@pxref{Switching + To create a new branch at an older revision (one that is no longer +the head of a branch), first select that revision (@pxref{Switching Branches}). Your procedure will then differ depending on whether you are using a locking or merging-based VCS. On a locking VCS, you will need to lock the old revision branch with @kbd{C-x v v}. You'll be asked to confirm, when you lock the old revision, that you really mean to create a new branch---if you say no, -you'll be offered a chance to lock the latest revision instead. On -a merging-based VCS you will skip this step. +you'll be offered a chance to lock the latest revision instead. On a +merging-based VCS you will skip this step. Then make your changes and type @kbd{C-x v v} again to commit a new -revision. This automatically creates a new branch starting from the -selected revision. You need not specially request a new branch, -because that's the only way to add a new revision at a point that is -not the head of a branch. - - After the branch is created, you ``stay'' on it. That means that -subsequent commits create new revisions on that branch. To leave the -branch, you must explicitly select a different revision with @kbd{C-u C-x -v v}. To transfer changes from one branch to another, use the merge -command, described in the next section. - -@node Merging -@subsubsection Merging Branches - -@cindex merging changes - When you have finished the changes on a certain branch, you will -often want to incorporate them into the file's main line of development -(the trunk). This is not a trivial operation, because development might -also have proceeded on the trunk, so that you must @dfn{merge} the -changes into a file that has already been changed otherwise. VC allows -you to do this (and other things) with the @code{vc-merge} command. - -@table @kbd -@item C-x v m (vc-merge) -Merge changes into the work file. -@end table - -@kindex C-x v m -@findex vc-merge - @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it -into the current version of the work file. It firsts asks you in the -minibuffer where the changes should come from. If you just type -@key{RET}, Emacs merges any changes that were made on the same branch -since you checked the file out (we call this @dfn{merging the news}). -This is the common way to pick up recent changes from the repository, -regardless of whether you have already changed the file yourself. - - You can also enter a branch ID or a pair of revision IDs in -the minibuffer. Then @kbd{C-x v m} finds the changes from that -branch, or the differences between the two revisions you specified, and -merges them into the current revision of the current file. - - As an example, suppose that you have finished a certain feature on -branch 1.3.1. In the meantime, development on the trunk has proceeded -to revision 1.5. To merge the changes from the branch to the trunk, -first go to the head revision of the trunk, by typing @kbd{C-u C-x v v -@key{RET}}. Revision 1.5 is now current. If locking is used for the file, -type @kbd{C-x v v} to lock revision 1.5 so that you can change it. Next, -type @kbd{C-x v m 1.3.1 @key{RET}}. This takes the entire set of changes on -branch 1.3.1 (relative to revision 1.3, where the branch started, up to -the last revision on the branch) and merges it into the current revision -of the work file. You can now commit the changed file, thus creating -revision 1.6 containing the changes from the branch. - - It is possible to do further editing after merging the branch, before -the next commit. But it is usually wiser to commit the merged -revision, then lock it and make the further changes. This will keep -a better record of the history of changes. - -@cindex conflicts -@cindex resolving conflicts - When you merge changes into a file that has itself been modified, the -changes might overlap. We call this situation a @dfn{conflict}, and -reconciling the conflicting changes is called @dfn{resolving a -conflict}. - - Whenever conflicts occur during merging, VC detects them, tells you -about them in the echo area, and asks whether you want help in merging. -If you say yes, it starts an Ediff session (@pxref{Top, -Ediff, Ediff, ediff, The Ediff Manual}). - - If you say no, the conflicting changes are both inserted into the -file, surrounded by @dfn{conflict markers}. The example below shows how -a conflict region looks; the file is called @samp{name} and the current -master file revision with user B's changes in it is 1.11. - -@c @w here is so CVS won't think this is a conflict. -@smallexample -@group -@w{<}<<<<<< name - @var{User A's version} -======= - @var{User B's version} -@w{>}>>>>>> 1.11 -@end group -@end smallexample - -@findex vc-resolve-conflicts - Then you can resolve the conflicts by editing the file manually. Or -you can type @code{M-x vc-resolve-conflicts} after visiting the file. -This starts an Ediff session, as described above. Don't forget to -commit the merged version afterwards. - -@findex vc-find-conflicted-file - If there is more than one conflicted file in a merge, type @kbd{M-x -vc-find-conflicted-file} after resolving the conflicts in each file. -This command visits the next conflicted file, and moves point to the -first conflict marker in that file. - -@node Multi-User Branching -@subsubsection Multi-User Branching - - It is often useful for multiple developers to work simultaneously on -different branches of a file. CVS and later systems allow this by -default; for RCS, it is possible if you create multiple source -directories. Each source directory should have a link named -@file{RCS} which points to a common directory of RCS master files. -Then each source directory can have its own choice of selected -revisions, but all share the same common RCS records. - - This technique works reliably and automatically, provided that the -source files contain RCS version headers -@iftex -(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Version Headers}). -@end ifnottex -The headers enable Emacs to be sure, at all times, which revision -ID is present in the work file. - - If the files do not have version headers, you must instead tell Emacs -explicitly in each session which branch you are working on. To do this, -first find the file, then type @kbd{C-u C-x v v} and specify the correct -branch ID. This ensures that Emacs knows which branch it is using -during this particular editing session. +revision. This creates a new branch starting from the selected +revision. + + After the branch is created, subsequent commits create new revisions +on that branch. To leave the branch, you must explicitly select a +different revision with @kbd{C-u C-x v v}. @ifnottex @include vc1-xtra.texi === modified file 'doc/emacs/vc1-xtra.texi' --- doc/emacs/vc1-xtra.texi 2011-01-26 08:36:39 +0000 +++ doc/emacs/vc1-xtra.texi 2011-12-20 03:00:10 +0000 @@ -495,14 +495,7 @@ VC does not normally use the information contained in these headers. The exception is RCS---with RCS, version headers are sometimes more reliable than the master file to determine which version of the file -you are editing. Note that in a multi-branch environment, version -headers are necessary to make VC behave correctly -@iftex -(@pxref{Multi-User Branching,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Multi-User Branching}). -@end ifnottex +you are editing. Searching for RCS version headers is controlled by the variable @code{vc-consult-headers}. If it is non-@code{nil} (the default), === modified file 'etc/NEWS' --- etc/NEWS 2011-12-19 07:25:46 +0000 +++ etc/NEWS 2011-12-20 03:00:10 +0000 @@ -833,19 +833,21 @@ ** VC and related modes ++++ *** Support for pulling on distributed version control systems. -The vc-pull command runs a "pull" operation, if it is supported. -This updates the current branch from upstream. A prefix argument -means to prompt the user for specifics, e.g. a pull location. +`C-x v +' (`vc-pull') runs a "pull" operation, if it is supported, to +update the current branch and working tree. A prefix argument means +to prompt the user for specifics, e.g. a pull location. **** `vc-update' is now an alias for `vc-pull'. **** Currently supported by Bzr, Git, and Mercurial. ++++ *** Support for merging on distributed version control systems. -The vc-merge command now runs a "merge" operation, if it is supported. -This merges another branch into the current one. This command prompts -the user for specifics, e.g. a merge source. +The vc-merge command now runs a "merge" operation, if it is supported, +to merge changes from another branch into the current one. It prompts +for specifics, e.g. a merge source. **** Currently supported for Bzr, Git, and Mercurial. ------------------------------------------------------------ revno: 106703 committer: Juanma Barranquero branch nick: trunk timestamp: Mon 2011-12-19 16:46:50 +0100 message: Fix typos. diff: === modified file 'ChangeLog' --- ChangeLog 2011-12-17 00:51:40 +0000 +++ ChangeLog 2011-12-19 15:46:50 +0000 @@ -2262,7 +2262,7 @@ 2009-12-10 Jan Djärv - * configure.in: Check for RSVG if GNUStep is used. + * configure.in: Check for RSVG if GNUstep is used. 2009-12-09 Jan Djärv @@ -2447,7 +2447,7 @@ 2009-05-06 Stefan Monnier - * configure.in: Don't define CANNOT_DUMP for GNUStep any more. + * configure.in: Don't define CANNOT_DUMP for GNUstep any more. 2009-05-05 Per Starbäck (tiny change) === modified file 'lisp/ChangeLog' --- lisp/ChangeLog 2011-12-19 07:00:16 +0000 +++ lisp/ChangeLog 2011-12-19 15:46:50 +0000 @@ -18,12 +18,12 @@ * term/ns-win.el (ns-get-selection-internal) (ns-store-selection-internal): Declare. - (ns-store-cut-buffer-internal, ns-get-cut-buffer-internal): Declare - as obsolete. - (ns-get-pasteboard, ns-paste-secondary): Use - ns-get-selection-internal. - (ns-set-pasteboard, ns-copy-including-secondary): Use - ns-store-selection-internal. + (ns-store-cut-buffer-internal, ns-get-cut-buffer-internal): + Declare as obsolete. + (ns-get-pasteboard, ns-paste-secondary): + Use ns-get-selection-internal. + (ns-set-pasteboard, ns-copy-including-secondary): + Use ns-store-selection-internal. 2011-12-17 Chong Yidong @@ -642,8 +642,8 @@ 2011-11-21 Juri Linkov - * calc/calc.el (calc-read-key-sequence): Let-bind `input-method-function' - to nil. (Bug#10018) + * calc/calc.el (calc-read-key-sequence): + Let-bind `input-method-function' to nil. (Bug#10018) 2011-11-21 Lars Magne Ingebrigtsen @@ -2173,11 +2173,10 @@ 2011-09-24 Ulf Jasper * net/newst-reader.el (newsticker-html-renderer) - (newsticker-show-news): Automatically - load html rendering package if newsticker-html-renderer is set. - Fixes "Warning: defvar ignored because w3m-fill-column is - let-bound" and the error "Symbol's value as variable is void: - w3m-fill-column". + (newsticker-show-news): Automatically load html rendering package + if newsticker-html-renderer is set. Fixes "Warning: defvar ignored + because w3m-fill-column is let-bound" and the error "Symbol's value + as variable is void: w3m-fill-column". 2011-09-24 Michael Albinus @@ -2291,8 +2290,8 @@ 2011-09-21 Martin Rudalics * window.el (set-window-buffer-start-and-point): - Call set-window-start with NOFORCE argument t. Suggested by Thierry - Volpiatto . + Call set-window-start with NOFORCE argument t. + Suggested by Thierry Volpiatto . (quit-window): Reword doc-string. Handle new format of quit-restore parameter. Don't delete window if it has a previous buffer we can show instead of the present one. @@ -2410,13 +2409,13 @@ 2011-09-18 Juri Linkov * info.el (Info-mode-syntax-table): New variable. - (Info-mode): Set `:syntax-table' to `Info-mode-syntax-table'. (Bug#3312) + (Info-mode): Set `:syntax-table' to `Info-mode-syntax-table' (bug#3312). 2011-09-18 Juri Linkov - * info.el (Info-file-supports-index-cookies): Increment - line-beginning-position's arg from 3 to 4 because makeinfo outputs - one more line for long file names (bug#4142). + * info.el (Info-file-supports-index-cookies): + Increment line-beginning-position's arg from 3 to 4 because makeinfo + outputs one more line for long file names (bug#4142). 2011-09-18 Chong Yidong @@ -4708,8 +4707,8 @@ pending encryption. (allout-inhibit-auto-save-info-for-decryption): - Adjust buffer-saved-size and some allout state to inhibit auto-saves if - there are plain-text topics pending encryption. + Adjust buffer-saved-size and some allout state to inhibit auto-saves + if there are plain-text topics pending encryption. (allout-maybe-resume-auto-save-info-after-encryption): Adjust buffer-saved-size and some allout state to not inhibit auto-saves @@ -6139,11 +6138,11 @@ (split-window-keep-point): Mention split-window-above-each-other instead of split-window-vertically. (split-window-above-each-other, split-window-vertically): - Rename split-window-vertically to split-window-above-each-other and - provide defalias for old definition. - (split-window-side-by-side, split-window-horizontally): Rename - split-window-horizontally to split-window-side-by-side and provide - defalias for the old definition. + Rename split-window-vertically to split-window-above-each-other + and provide defalias for old definition. + (split-window-side-by-side, split-window-horizontally): + Rename split-window-horizontally to split-window-side-by-side + and provide defalias for the old definition. (ctl-x-map): Move bindings for delete-window, delete-other-windows and enlarge-window here from window.c. Replace bindings for split-window-vertically and @@ -9566,10 +9565,10 @@ preserves the existing header prefix, rebulleting it if necessary, rather than replacing it. This is necessary for proper operation of cooperative addons like allout-widgets. - (allout-make-topic-prefix, allout-rebullet-heading): Change - SOLICIT arg to INSTEAD, and interpret additionally a string value - as alternate bullet to be used, instead of prompting the user for - a bullet character. + (allout-make-topic-prefix, allout-rebullet-heading): + Change SOLICIT arg to INSTEAD, and interpret additionally a string + value as alternate bullet to be used, instead of prompting the user + for a bullet character. 2011-03-09 Michael Albinus === modified file 'lisp/ChangeLog.14' --- lisp/ChangeLog.14 2011-12-14 21:05:20 +0000 +++ lisp/ChangeLog.14 2011-12-19 15:46:50 +0000 @@ -3473,7 +3473,7 @@ 2009-01-10 Dan Nicolaescu * diff-mode.el (diff-show-trailing-whitespaces): Remove function. - Move setting up whitepace-mode ... + Move setting up whitespace-mode ... (diff-mode): ... here. (diff-mode-menu): Add a menu entry for showing trailing whitespace. === modified file 'lisp/mh-e/ChangeLog.1' --- lisp/mh-e/ChangeLog.1 2011-12-06 01:30:54 +0000 +++ lisp/mh-e/ChangeLog.1 2011-12-19 15:46:50 +0000 @@ -1648,7 +1648,7 @@ * mh-e.el (mh-version): Do something sensible when mh-variant-in-use is undefined. * mh-junk.el (mh-spamassassin-blacklist) - (mh-spamassassin-whitelist): Change options to be compatoble with + (mh-spamassassin-whitelist): Change options to be compatible with old version of spamassassin (V2.20). 2003-09-07 Mark D. Baushke === modified file 'src/ChangeLog.11' --- src/ChangeLog.11 2011-12-15 07:24:10 +0000 +++ src/ChangeLog.11 2011-12-19 15:46:50 +0000 @@ -12897,7 +12897,7 @@ * font.c (font_update_drivers): Sanity fallback to avoid disabling all drivers. - * nsterm.m (-windowDidResize:): Avoid inf-loop under GNUStep. + * nsterm.m (-windowDidResize:): Avoid inf-loop under GNUstep. 2009-05-06 YAMAMOTO Mitsuharu ------------------------------------------------------------ revno: 106702 committer: Sam Steingold branch nick: trunk timestamp: Mon 2011-12-19 10:15:11 -0500 message: * lisp/cedet/semantic/edit.el (semantic-edits-incremental-parser): Add the autoload cookie, necessary for JDEE. diff: === modified file 'lisp/cedet/ChangeLog' --- lisp/cedet/ChangeLog 2011-12-06 01:30:54 +0000 +++ lisp/cedet/ChangeLog 2011-12-19 15:15:11 +0000 @@ -1,3 +1,8 @@ +2011-12-19 Sam Steingold + + * semantic/edit.el (semantic-edits-incremental-parser): Add the + autoload cookie, necessary for JDEE. + 2011-12-06 Juanma Barranquero * semantic/bovine/c.el (semantic-tag-abstract-p): Fix typo. === modified file 'lisp/cedet/semantic/edit.el' --- lisp/cedet/semantic/edit.el 2011-12-04 08:02:42 +0000 +++ lisp/cedet/semantic/edit.el 2011-12-19 15:15:11 +0000 @@ -470,6 +470,7 @@ (buffer-name (current-buffer)))) (run-hooks 'semantic-edits-incremental-reparse-failed-hook)) +;;;###autoload (defun semantic-edits-incremental-parser () "Incrementally reparse the current buffer. Incremental parser allows semantic to only reparse those sections of ------------------------------------------------------------ revno: 106701 committer: Glenn Morris branch nick: trunk timestamp: Mon 2011-12-19 06:21:17 -0500 message: Auto-commit of loaddefs files. diff: === modified file 'lisp/mail/rmail.el' --- lisp/mail/rmail.el 2011-12-10 13:48:35 +0000 +++ lisp/mail/rmail.el 2011-12-19 11:21:17 +0000 @@ -4527,7 +4527,7 @@ ;;;*** -;;;### (autoloads (rmail-mime) "rmailmm" "rmailmm.el" "2cb1f29b88b0c724fdba389fd7b98b00") +;;;### (autoloads (rmail-mime) "rmailmm" "rmailmm.el" "91f72e39e6ea7c2be098fe3f05174b9e") ;;; Generated autoloads from rmailmm.el (autoload 'rmail-mime "rmailmm" "\ ------------------------------------------------------------ revno: 106700 committer: Chong Yidong branch nick: trunk timestamp: Mon 2011-12-19 15:25:46 +0800 message: More updates for VC documentation. * doc/emacs/maintaining.texi (VCS Merging, VCS Changesets): Index entries. (VC Mode Line): Add index entry for "version control status". (VC Undo): Use vc-revert instead of its vc-revert-buffer alias. Document vc-revert-show-diff. De-document vc-rollback. (VC Directory Mode): Rewrite introduction. Move prefix arg documentation here from VC Directory Buffer node. (VC Directory Buffer): Use a decentralized VCS example. (VC Directory Commands): Use a table. Remove material duplicated in previous nodes on multi-file VC filsets. diff: === modified file 'admin/FOR-RELEASE' --- admin/FOR-RELEASE 2011-11-28 11:12:00 +0000 +++ admin/FOR-RELEASE 2011-12-19 07:25:46 +0000 @@ -61,13 +61,6 @@ * BUGS -** Does deleting frames run Lisp code? If so, can we get rid of that? -It is a dangerous design. -http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg01330.html - -** Why were the calls to x_fully_uncatch_errors commented out in eval.c? -http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg01987.html - ** rms: gnus-dired.el is a mistake. Those features should not be part of Gnus. They should be moved to some other part of Emacs. rsteib: Gnus dependencies in `gnus-dired.el' (and `mailcap.el') have been @@ -90,25 +83,8 @@ `log-edit-comment-search-forward'. Perhaps search commands on the global key binding `M-s' are useless in these modes. -** sdl.web@gmail.com, 30 Oct: ps-lpr-switches has no effect -http://lists.gnu.org/archive/html/emacs-devel/2007-10/msg02091.html - -Fixed by this change? - -2007-11-09 Vinicius Jose Latorre - - * ps-print.el: [...] - (ps-do-despool): If ps-lpr-switches is not a list, force it to be one. - -** In C, use EMACS_INT for variables and structure members -for buffer/string positions. E.g. struct it, struct text_pos. - * DOCUMENTATION -** Clean up Emacs.app references in code and documentation. - -** Document new font backend - ** Document XEmbed support ** Check the Emacs Tutorial. @@ -154,7 +130,7 @@ arevert-xtra.texi cyd basic.texi cyd buffers.texi cyd -building.texi +building.texi cyd calendar.texi cal-xtra.texi cmdargs.texi @@ -188,13 +164,13 @@ mule.texi m-x.texi cyd picture-xtra.texi -programs.texi +programs.texi cyd regs.texi cyd rmail.texi screen.texi cyd search.texi cyd sending.texi -text.texi +text.texi cyd trouble.texi vc-xtra.texi vc1-xtra.texi === modified file 'doc/emacs/ChangeLog' --- doc/emacs/ChangeLog 2011-12-17 07:50:08 +0000 +++ doc/emacs/ChangeLog 2011-12-19 07:25:46 +0000 @@ -1,3 +1,15 @@ +2011-12-19 Chong Yidong + + * maintaining.texi (VCS Merging, VCS Changesets): Index entries. + (VC Mode Line): Add index entry for "version control status". + (VC Undo): Use vc-revert instead of its vc-revert-buffer alias. + Document vc-revert-show-diff. De-document vc-rollback. + (VC Directory Mode): Rewrite introduction. Move prefix arg + documentation here from VC Directory Buffer node. + (VC Directory Buffer): Use a decentralized VCS example. + (VC Directory Commands): Use a table. Remove material duplicated + in previous nodes on multi-file VC filsets. + 2011-12-17 Chong Yidong * maintaining.texi (VCS Concepts): Make "revision" terminology === modified file 'doc/emacs/maintaining.texi' --- doc/emacs/maintaining.texi 2011-12-17 07:50:08 +0000 +++ doc/emacs/maintaining.texi 2011-12-19 07:25:46 +0000 @@ -227,17 +227,18 @@ @node VCS Merging @subsubsection Merge-based vs lock-based Version Control -@cindex locking versus merging A version control system typically has some mechanism to coordinate between users who want to change the same file. There are two ways to do this: merging and locking. +@cindex merging-based version In a version control system that uses merging, each user may modify a work file at any time. The system lets you @dfn{merge} your work file, which may contain changes that have not been committed, with the latest changes that others have committed. +@cindex locking-based version Older version control systems use a @dfn{locking} scheme instead. Here, work files are normally read-only. To edit a file, you ask the version control system to make it writable for you by @dfn{locking} @@ -274,7 +275,7 @@ @node VCS Changesets @subsubsection Changeset-based vs File-based Version Control -@cindex changesets +@cindex file-based version control On SCCS, RCS, CVS, and other early version control systems, version control operations are @dfn{file-based}: each file has its own comment and revision history separate from that of all other files. Newer @@ -283,6 +284,7 @@ changes is handled as a unit. Any comment associated with the change does not belong to a single file, but to the changeset itself. +@cindex changeset-based version control Changeset-based version control is more flexible and powerful than file-based version control; usually, when a change to multiple files has to be reversed, it's good to be able to easily identify and remove @@ -356,20 +358,22 @@ @node VC Mode Line @subsection Version Control and the Mode Line -@cindex VC, mode line indicator +@cindex VC mode line indicator When you visit a file that is under version control, Emacs indicates this on the mode line. For example, @samp{Bzr-1223} says that Bazaar is used for that file, and the current revision ID is 1223. +@cindex version control status The character between the back-end name and the revision ID -indicates the status of the work file. In a merge-based version -control system, a @samp{-} character indicates that the work file is -unmodified, and @samp{:} indicates that it has been modified. -@samp{!} indicates that the file contains conflicts as result of a -recent merge operation (@pxref{Merging}), or that the file was removed -from the version control. Finally, @samp{?} means that the file is -under version control, but is missing from the working tree. +indicates the @dfn{version control status} of the work file. In a +merge-based version control system, a @samp{-} character indicates +that the work file is unmodified, and @samp{:} indicates that it has +been modified. @samp{!} indicates that the file contains conflicts as +result of a recent merge operation (@pxref{Merging}), or that the file +was removed from the version control. Finally, @samp{?} means that +the file is under version control, but is missing from the working +tree. In a lock-based system, @samp{-} indicates an unlocked file, and @samp{:} a locked file; if the file is locked by another user (for @@ -399,6 +403,7 @@ @subsection Basic Editing under Version Control @cindex filesets, VC +@cindex VC filesets Most VC commands operate on @dfn{VC filesets}. A VC fileset is a collection of one or more files that a VC operation acts on. When you type VC commands in a buffer visiting a version-controlled file, the @@ -451,9 +456,9 @@ @itemize @bullet @item If there is more than one file in the VC fileset and the files have -inconsistent version control states, signal an error. (Note, however, -that a fileset is allowed to include both ``newly-added'' files and -``modified'' files; @pxref{Registering}.) +inconsistent version control statuses, signal an error. (Note, +however, that a fileset is allowed to include both ``newly-added'' +files and ``modified'' files; @pxref{Registering}.) @item If none of the files in the VC fileset are registered with a version @@ -504,7 +509,7 @@ @itemize @bullet @item If there is more than one file in the VC fileset and the files have -inconsistent version control states, signal an error. +inconsistent version control statuses, signal an error. @item If each file in the VC fileset is not registered with a version @@ -887,7 +892,7 @@ @table @kbd @item C-x v l -Display revision control state and change history +Display the change history for the current fileset (@code{vc-print-log}). @item C-x v L @@ -927,8 +932,8 @@ maximum number of revisions to display. The @kbd{C-x v L} history is shown in a compact form, usually -omitting all but the first line of each log entry. However, you can -type @key{RET} (@code{log-view-toggle-entry-display}) in the +showing only the first line of each log entry. However, you can type +@key{RET} (@code{log-view-toggle-entry-display}) in the @samp{*vc-change-log*} buffer to reveal the entire log entry for the revision at point. A second @key{RET} hides it again. @@ -1008,58 +1013,67 @@ @table @kbd @item C-x v u -Revert the buffer and the file to the working revision from which you started -editing the file. - -@item C-x v c -Remove the last-entered change from the master for the visited file. -This undoes your last commit. +Revert the work file(s) in the current VC fileset to the last revision +(@code{vc-revert}). @end table +@c `C-x v c' (vc-rollback) was removed, since it's RCS/SCCS specific. + @kindex C-x v u -@findex vc-revert-buffer - If you want to discard your current set of changes and revert to the -working revision from which you started editing the file, use @kbd{C-x -v u} (@code{vc-revert-buffer}). If the version control system is -locking-based, this leaves the file unlocked, and you must lock it -again before making new changes. @kbd{C-x v u} requires confirmation, -unless it sees that you haven't made any changes with respect to the -master copy of the working revision. - - @kbd{C-x v u} is also the command to unlock a file if you lock it and -then decide not to change it. - -@kindex C-x v c -@findex vc-rollback - To cancel a change that you already committed, use @kbd{C-x v c} -(@code{vc-rollback}). This command discards all record of the most -recent checked-in revision, but only if your work file corresponds to -that revision---you cannot use @kbd{C-x v c} to cancel a revision that -is not the latest on its branch. Note that many version control -systems do not support rollback at all; this command is something of a -historical relic. +@findex vc-revert +@vindex vc-revert-show-diff + If you want to discard all the changes you have made to the current +VC fileset, type @kbd{C-x v u} (@code{vc-revert-buffer}). This shows +you a diff between the work file(s) and the revision from which you +started editing, and asks for confirmation for discarding the changes. +If you agree, the fileset is reverted. If you don't want @kbd{C-x v +u} to show a diff, set the variable @code{vc-revert-show-diff} to +@code{nil} (you can still view the diff directly with @kbd{C-x v =}; +@pxref{Old Revisions}). Note that @kbd{C-x v u} cannot be reversed +with the usual undo commands (@pxref{Undo}), so use it with care. + + On locking-based version control systems, @kbd{C-x v u} leaves files +unlocked; you must lock again to resume editing. You can also use +@kbd{C-x v u} to unlock a file if you lock it and then decide not to +change it. @node VC Directory Mode @subsection VC Directory Mode +@cindex VC Directory buffer + The @dfn{VC Directory buffer} is a specialized buffer for viewing +the version control statuses of the files in a directory tree, and +performing version control operations on those files. In particular, +it is used to specify multi-file VC filesets for commands like +@w{@kbd{C-x v v}} to act on (@pxref{VC Directory Commands}). + @kindex C-x v d @findex vc-dir - When you are working on a large program, it is often useful to find -out which files have changed within an entire directory tree, or to -view the status of all files under version control at once, and to -perform version control operations on collections of files. You can -use the command @kbd{C-x v d} (@code{vc-dir}) to make a directory -listing that includes only files relevant for version control. This -creates a @dfn{VC Directory buffer} and displays it in a separate -window. - + To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}). +This reads a directory name using the minibuffer, and switches to a VC +Directory buffer for that directory. By default, the buffer is named +@samp{*vc-dir*}. Its contents are described +@iftex +below. +@end iftex +@ifnottex +in @ref{VC Directory Buffer}. +@end ifnottex + + The @code{vc-dir} command automatically detects the version control +system to be used in the specified directory. In the event that more +than one system is being used in the directory, you should invoke the +command with a prefix argument, @kbd{C-u C-x v d}; this prompts for +the version control system which the VC Directory buffer should use. + +@ifnottex @cindex PCL-CVS @pindex cvs @cindex CVS directory mode - The VC Directory buffer works with all the version control systems -that VC supports. For CVS, Emacs also offers a more powerful facility -called PCL-CVS. @xref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The -Emacs Front-End to CVS}. + In addition to the VC Directory buffer, Emacs has a similar facility +called PCL-CVS which is specialized for CVS. @xref{Top, , About +PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}. +@end ifnottex @menu * Buffer: VC Directory Buffer. What the buffer looks like and means. @@ -1070,152 +1084,188 @@ @subsubsection The VC Directory Buffer The VC Directory buffer contains a list of version-controlled files -in the current directory and its subdirectories. Files which are -up-to-date (have no local differences from the repository copy) are -usually hidden; if all files in a subdirectory are up-to-date, the -subdirectory is hidden as well. There is an exception to this rule: -if VC mode detects that a file has changed to an up-to-date state -since you last looked at it, that file and its state are shown. - - If a directory uses more that one version control system, you can -select which system to use for the @code{vc-dir} command by invoking -@code{vc-dir} with a prefix argument: @kbd{C-u C-x v d}. - - The line for an individual file shows the version control state of -the file. Under RCS and SCCS, the name of the user locking the file -is shown; under CVS, an abbreviated version of the @samp{cvs status} -output is used. Here is an example using CVS: +and their version control statuses. It lists files in the current +directory (the one specified when you called @kbd{C-x v d}) and its +subdirectories, but only those with a ``noteworthy'' status. Files +that are up-to-date (i.e.@: the same as in the repository) are +omitted. If all the files in a subdirectory are up-to-date, the +subdirectory is not listed either. As an exception, if a file has +become up-to-date as a direct result of a VC command, it is listed. + + Here is an example of a VC Directory buffer listing: @smallexample @group - ./ - modified file1.c - needs-update file2.c - needs-merge file3.c + ./ + edited configure.ac +* added README + unregistered temp.txt + src/ +* edited src/main.c @end group @end smallexample @noindent -In this example, @samp{file1.c} is modified with respect to the -repository, and @samp{file2.c} is not. @samp{file3.c} is modified, -but other changes have also been committed---you need to merge them -with the work file before you can check it in. - +Two work files have been modified but not committed: +@file{configure.ac} in the current directory, and @file{foo.c} in the +@file{src/} subdirectory. The file named @file{README} has been added +but is not yet committed, while @file{temp.txt} is not under version +control (@pxref{Registering}). + +The @samp{*} characters next to the entries for @file{README} and +@file{src/main.c} indicate that the user has marked out these files as +the current VC fileset +@iftex +(see below). +@end iftex +@ifnottex +(@pxref{VC Directory Commands}). +@end ifnottex + + The above example is typical for a decentralized version control +system like Bazaar, Git, or Mercurial. Other systems can show other +statuses. For instance, CVS shows the @samp{needs-update} status if +the repository has changes that have not been applied to the work +file. RCS and SCCS show the name of the user locking a file as its +status. + +@ifnottex @vindex vc-stay-local @vindex vc-cvs-stay-local - In the above, if the repository were on a remote machine, VC only -contacts it when the variable @code{vc-stay-local} (or -@code{vc-cvs-stay-local}) is @code{nil} -@iftex -(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{CVS Options}). + On CVS and Subversion, the @code{vc-dir} command normally contacts +the repository, which may be on a remote machine, to check for +updates. If you change the variable @code{vc-stay-local} or +@code{vc-cvs-stay-local} (for CVS) to @code{nil} (@pxref{CVS +Options}), then Emacs avoids contacting a remote repository when +generating the VC Directory buffer (it will still contact it when +necessary, e.g.@: when doing a commit). This may be desirable if you +are working offline or the network is slow. @end ifnottex -This is because access to the repository may be slow, or you may be -working offline and not have access to the repository at all. As a -consequence, VC would not be able to tell you that @samp{file3.c} is -in the ``merge'' state; you would learn that only when you try to -commit your modified copy of the file, or use a command such as -@kbd{C-x v m}. - - In practice, this is not a problem because CVS handles this case -consistently whenever it arises. In VC, you'll simply get prompted to -merge the remote changes into your work file first. The benefits of -less network communication usually outweigh the disadvantage of not -seeing remote changes immediately. @vindex vc-directory-exclusion-list - When a VC directory displays subdirectories it omits some that -should never contain any files under version control. By default, -this includes Version Control subdirectories such as @samp{RCS} and -@samp{CVS}; you can customize this by setting the variable -@code{vc-directory-exclusion-list}. + The VC Directory buffer omits subdirectories listed in the variable +@code{vc-directory-exclusion-list}. The default value of this +variable contains directories that are used internally by version +control systems. @node VC Directory Commands @subsubsection VC Directory Commands - VC Directory mode has a full set of navigation and marking commands -for picking out filesets. Some of these are also available in a -context menu invoked by @kbd{mouse-2}. - - Up- and down-arrow keys move in the buffer; @kbd{n} and @kbd{p} also -move vertically as in other list-browsing modes. @key{SPC} and -@key{TAB} behave like down-arrow, and @key{BackTab} behaves like -up-arrow. - - Both @kbd{C-m} and @kbd{f} visit the file on the current -line. @kbd{o} visits that file in another window. @kbd{q} dismisses -the directory buffer. - - @kbd{x} hides up-to-date files. - - @kbd{m} marks the file or directory on the current line. If the -region is active, @kbd{m} marks all the files in the region. There -are some restrictions when marking: a file cannot be marked if any of -its parent directories are marked, and a directory cannot be marked if -any files in it or in its child directories are marked. - - @kbd{M} marks all the files with the same VC state as the current -file if the cursor is on a file. If the cursor is on a directory, it -marks all child files. With a prefix argument: marks all files and -directories. - - @kbd{u} unmarks the file or directory on the current line. If the -region is active, it unmarks all the files in the region. - - @kbd{U} marks all the files with the same VC state as the current file -if the cursor is on a file. If the cursor is on a directory, it -unmarks all child files. With a prefix argument: unmarks all marked + Emacs provides several commands for navigating the VC Directory +buffer, and for ``marking'' files as belonging to the current VC +fileset. + +@table @kbd +@item n +@itemx @key{SPC} +Move point to the next entry (@code{vc-dir-next-line}). + +@item p +Move point to the previous entry (@code{vc-dir-previous-line}). + +@item @key{TAB} +Move to the next directory entry (@code{vc-dir-next-directory}). + +@item S-@key{TAB} +Move to the previous directory entry +(@code{vc-dir-previous-directory}). + +@item @key{RET} +@itemx f +Visit the file or directory listed on the current line +(@code{vc-dir-find-file}). + +@item o +Visit the file or directory on the current line, in a separate window +(@code{vc-dir-find-file-other-window}). + +@item m +Mark the file or directory on the current line (@code{vc-dir-mark}), +putting it in the current VC fileset. If the region is active, mark +all files in the region. + +A file cannot be marked with this command if it is already in a marked +directory, or one of its subdirectories. Similarly, a directory +cannot be marked with this command if any file in its tree is marked. + +@item M +If point is on a file entry, mark all files with the same status; if +point is on a directory entry, mark all files in that directory tree +(@code{vc-dir-mark-all-files}). With a prefix argument, mark all +listed files and directories. + +@item u +Unmark the file or directory on the current line. If the region is +active, unmark all the files in the region (@code{vc-dir-unmark}). + +@item U +If point is on a file entry, umark all files with the same status; if +point is on a directory entry, unmark all files in that directory tree +(@code{vc-dir-unmark-all-files}). With a prefix argument, unmark all files and directories. - It is possible to do search, search and replace, incremental search, -and incremental regexp search on multiple files. These commands will -work on all the marked files or the current file if nothing is marked. -If a directory is marked, the files in that directory shown in the VC -directory buffer will be used. - - @kbd{S} searches the marked files. - - @kbd{Q} does a query replace on the marked files. - - @kbd{M-s a C-s} does an incremental search on the marked files. - - @kbd{M-s a C-M-s} does an incremental regular expression search -on the marked files. +@item x +Hide files with @samp{up-to-date} status +(@code{vc-dir-hide-up-to-date}). + +@item q +Quit the VC Directory buffer, and bury it (@code{quit-window}). +@end table + +@findex vc-dir-mark +@findex vc-dir-mark-all-files + While in the VC Directory buffer, all the files that you mark with +@kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark}) are in +the current VC fileset. If you mark a directory entry with @kbd{m}, +all the listed files in that directory tree are in the current VC +fileset. The files and directories that belong to the current VC +fileset are indicated with a @samp{*} character in the VC Directory +buffer, next to their VC status. In this way, you can set up a +multi-file VC fileset to be acted on by VC commands like @w{@kbd{C-x v +v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}} (@pxref{Old +Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}). + + The VC Directory buffer also defines some single-key shortcuts for +VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l}, +@kbd{i}, and @kbd{v}. + + For example, you can commit a set of edited files by opening a VC +Directory buffer, where the files are listed with the @samp{edited} +status; marking the files; and typing @kbd{v} or @kbd{C-x v v} +(@code{vc-next-action}). If the version control system is +changeset-based, Emacs will commit the files in a single revision. + + While in the VC Directory buffer, you can also perform search and +replace on the current VC fileset, with the following commands: + +@table @kbd +@item S +Search the fileset (@code{vc-dir-search}). + +@item Q +Do a regular expression query replace on the fileset +(@code{vc-dir-query-replace-regexp}). + +@item M-s a C-s +Do an incremental search on the fileset (@code{vc-dir-isearch}). + +@item M-s a C-M-s +Do an incremental regular expression search on the fileset +(@code{vc-dir-isearch-regexp}). +@end table + +@noindent +Apart from acting on multiple files, these commands behave much like +their single-buffer counterparts (@pxref{Search}). @cindex stashes in version control @cindex shelves in version control - Commands are also accessible from the VC-dir menu. Note that some -VC backends use the VC-dir menu to make available extra, -backend-specific, commands. For example, Git and Bazaar allow you to -manipulate @dfn{stashes} and @dfn{shelves}. (These provide a -mechanism to temporarily store uncommitted changes somewhere out of -the way, and bring them back at a later time.) - - Normal VC commands with the @kbd{C-x v} prefix work in VC directory -buffers. Some single-key shortcuts are available as well; @kbd{=}, -@kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with -@kbd{C-x v}. - - The command @kbd{C-x v v} (@code{vc-next-action}) operates on all -the marked files, so that you can commit several files at once. If -the underlying VC supports atomic commits of multiple-file changesets, -@kbd{C-x v v} with a selected set of modified but not committed files -will commit all of them at once as a single changeset. - - When @kbd{C-x v v} (@code{vc-next-action}) operates on multiple -files, all of those files must be either in the same state or in -compatible states (added, modified and removed states are considered -compatible). Otherwise it signals an error. This differs from the -behavior of older versions of VC, which did not have fileset -operations and simply did @code{vc-next-action} on each file -individually. - - If any files are in a state that calls for commit, @kbd{C-x v v} reads a -single log entry and uses it for the changeset as a whole. If the -underling VCS is file- rather than changeset-oriented, the log entry -will be replicated into the history of each file. + The above commands are also available via the menu bar, and via a +context menu invoked by @kbd{Mouse-2}. Furthermore, some VC backends +use the menu to provide extra backend-specific commands. For example, +Git and Bazaar allow you to manipulate @dfn{stashes} and @dfn{shelves} +(where are a way to temporarily put aside uncommitted changes, and +bring them back at a later time). @node Branches @subsection Multiple Branches of a File === modified file 'etc/NEWS' --- etc/NEWS 2011-12-17 07:50:08 +0000 +++ etc/NEWS 2011-12-19 07:25:46 +0000 @@ -849,6 +849,7 @@ **** Currently supported for Bzr, Git, and Mercurial. ++++ *** New option `vc-revert-show-diff' controls whether `vc-revert' shows a diff while querying the user. It defaults to t.