From: Richard M. Stallman Date: Sat, 1 Nov 2008 01:58:34 +0000 (+0000) Subject: (Types of Log File): Change logs are older than version control. X-Git-Tag: emacs-pretest-23.0.90~2039 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=a11d373796f896363dfb69fac5c38c32c031e866;p=emacs.git (Types of Log File): Change logs are older than version control. (VCS Concepts): Simplify and rearrange. (Version Control Systems): Make it clear that Linux is only the kernel. (VC Mode Line): Shorten reference to menu item. (Basic VC Editing): Clarify VC fileset. Shorten and simplify. (VC Directory Mode): Minor cleanup. Unchanged files are hidden, not omitted. (VC Directory Commands): Shorten and simplify. (Change Log Commands): New node, split from Change Logs. (VC Directory Buffer): New node, split from VC Directory Mode. --- diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index a8ddec5270e..eb85f6a1e1d 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,17 @@ +2008-11-01 Richard M. Stallman + + * maintaining.texi (Types of Log File): Change logs are older than + version control. + (VCS Concepts): Simplify and rearrange. + (Version Control Systems): Make it clear that Linux is only the kernel. + (VC Mode Line): Shorten reference to menu item. + (Basic VC Editing): Clarify VC fileset. Shorten and simplify. + (VC Directory Mode): Minor cleanup. + Unchanged files are hidden, not omitted. + (VC Directory Commands): Shorten and simplify. + (Change Log Commands): New node, split from Change Logs. + (VC Directory Buffer): New node, split from VC Directory Mode. + 2008-10-31 Chong Yidong * misc.texi (Document View): Renamed from Document Files, moved here diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index 31a312d16dc..99f6ef0e8d4 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -170,7 +170,7 @@ sometimes invoke it from the command line. @cindex git @item Git is a distributed version control system invented by Linus Torvalds to support -Linux kernel development. It supports atomic commits of filesets and +development of Linux (his kernel). It supports atomic commits of filesets and file moving/renaming. One significant feature of git is that it largely abolishes the notion of a single centralized repository; instead, each working copy of a git project is its own repository and @@ -229,11 +229,10 @@ on the version control system; in the simplest case, it is just an integer. To go beyond these basic concepts, you will need to understand three -ways in which version control systems can differ from each other. +aspects in which version control systems differ. They can be locking-based or merging-based; they can be file-based or changeset-based; and they can be centralized or decentralized. VC -handles all these choices, but they lead to differing behaviors which -you will need to understand as you use it. +handles all these modes of operation, but it cannot hide the differences. @cindex locking versus merging A version control system typically has some mechanism to coordinate @@ -263,21 +262,21 @@ unable to because it is locked. In merging systems, @dfn{merge conflicts} happen when you check in a change to a file that conflicts with a change checked in by someone else after your checkout. Both kinds of conflict have to be resolved by human judgment and -communication. +communication. Experience has shown that merging is superior to +locking, both in convenience to developers and in minimizing the +number and severity of conflicts that actually occur. 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 -Mercurial, are exclusively merging-based. Experience has shown that -merging is superior to locking, both in convenience to developers and -in minimizing the number and severity of conflicts that actually -occur. Sometimes, however, newer version control systems may have -locks retrofitted onto them for reasons having nothing to do with -technology@footnote{Usually the control-freak instincts of managers.}. +Mercurial, are exclusively merging-based. - VC mode supports both locking and merging version control and tries -to hide the differences between them as much as possible. + VC mode supports both locking and merging version control. The +terms ``checkin'' and ``checkout'' come from locking-based version +control systems; newer version control systems have slightly different +operations usually called ``commit'' and ``update'', but VC hides the +differences between them as much as possible. @cindex files versus changesets. On SCCS, RCS, CVS, and other early version control systems, version @@ -292,33 +291,21 @@ but to the changeset itself. 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 -all of it. But it took some years for designers to figure that out, -and while file-based systems are passing out of use, there are lots of -legacy repositories still to be dealt with as of this writing (2008). - - Prior to Emacs 23, VC supported only file-based systems, leading to -unhappy results when it was used to drive changeset-based -systems---the Subversion support, for example, used to break up -changesets into multiple per-file commits. This has been fixed, but -it has left a mark in VC's terminology. The terms ``checkin'' and -``checkout'' are associated with file-based and locking-based systems -and a bit archaic; nowadays those operations are usually called -``commit'' and ``update''. +all of it. @cindex centralized vs. decentralized 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 problem with this approach is that a single -repository is a single point of failure---if the repository server is -down, all work stops. +kind of model. One of its drawbacks is that the repository is a choke +point for reliability and efficiency. - Newer version control systems like GNU Arch, git, Mercurial, and -Bazaar are @dfn{decentralized}. 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. At the -limit, each developer has his/her own repository, and repository -merges replace checkin/commit operations. + 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. At the limit, each developer has his/her own +repository, and repository merges replace checkin/commit operations. VC's job is to help you manage the traffic between your personal workfiles and a repository. Whether that repository is a single @@ -343,20 +330,14 @@ Log}). It provides a chronological record of all changes to a large portion of a program---typically one directory and its subdirectories. A small program would use one @file{ChangeLog} file; a large program may have a @file{ChangeLog} file in each major directory. -@xref{Change Log}. - - Actually, the fact that both kinds of log exist is partly a legacy -from file-based version control. Changelogs are a GNU convention, -later more widely adopted, that help developers to get a -changeset-based view of a project even when its version control system -has that information split up in multiple file-based logs. - - Changeset-based version systems, on the other hand, often maintain a -changeset-based modification log for the entire system that makes -ChangeLogs somewhat redundant. One advantage that ChangeLogs retain -is that it is sometimes useful to be able to view the transaction -history of a single directory separately from those of other -directories. +@xref{Change Log}. Programmers have used change logs since long +before version control systems. + + Changeset-based version systems typically maintain a changeset-based +modification log for the entire system, which makes change log files +somewhat redundant. One advantage that they retain is that it is +sometimes useful to be able to view the transaction history of a +single directory separately from those of other directories. A project maintained with version control can use just the version control log, or it can use both kinds of logs. It can handle some @@ -395,8 +376,7 @@ instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}. indicator to pop up a ``tool-tip'', which displays a more verbose description of the version control status. Pressing @kbd{Mouse-1} over the indicator pops up a menu of VC commands. This menu is -identical to the @samp{Version Control} menu item, which can be found -in the @samp{Tools} menu on the menu bar. +identical to the @samp{Tools / Version Control} menu item. @vindex auto-revert-check-vc-info When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is @@ -413,25 +393,23 @@ system, but is usually not excessive. @node Basic VC Editing @subsection Basic Editing under Version Control -@cindex filesets +@cindex filesets, VC Most VC commands operate on @dfn{VC filesets}. A VC fileset is a -group of one or more files that are treated as a unit, for the -purposes of version control. - - If you are visiting a version-controlled file in the current -buffer, the VC fileset is simply that one file. If you are visiting a -VC directory buffer, and some files in it are marked, the VC fileset +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 +VC fileset is simply that one file. When you type them in a VC +Directory buffer, and some files in it are marked, the VC fileset consists of the marked files (@pxref{VC Directory Mode}). The principal VC command is an all-purpose command, @kbd{C-x v v} (@code{vc-next-action}), that performs either locking, merging or a -check-in on the current VC fileset, depending on the situation. You -can call @kbd{C-x v v} from a version-controlled file, or from the VC -Directory buffer. +check-in (depending on the situation) on the current VC fileset. You +can use @kbd{C-x v v} in a file-visiting buffer or in a VC Directory +buffer. @table @kbd @itemx C-x v v -Perform the next logical version control operation on the VC fileset. +Perform the appropriate next version control operation on the VC fileset. @end table @findex vc-next-action @@ -450,15 +428,11 @@ command line. All files in a VC fileset must be under the same version control system; if they are not, Emacs signals an error when you attempt to execute a command on the fileset. - If you are accustomed to previous versions of VC, most of the -changes to VC in Emacs 23 are found in VC directory mode (@pxref{VC -Directory Mode}). When multiple files are marked in the VC directory -buffer, they are treated as a VC fileset; typing @kbd{C-x v v} in the -VC directory buffer passes them to the version control backends as a -single unit. Other commands in VC directory mode now act on the VC -fileset, rather than the file on the current line. These changes -allow VC to interoperate correctly with changeset-based version -control systems. + Support for VC filesets and changeset-based version control systems +is the main improvement to VC in Emacs 23. When you mark multi-file +VC in a VC Directory buffer, VC operations treat them as a VC fileset, +and operate on them all at once if the version control system is +changeset-based. @xref{VC Directory Mode} VC filesets are distinct from the ``named filesets'' used for viewing and visiting files in functional groups (@pxref{Filesets}). @@ -1001,19 +975,26 @@ window. @cindex PCL-CVS @pindex cvs @cindex CVS directory mode - The VC Directory buffer described here works with all the version -control systems that VC supports. Another more powerful facility, -designed specifically for CVS, is called PCL-CVS. @xref{Top, , About -PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}. + 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}. + +@menu +* Buffer: VC Directory Buffer. What the buffer looks like and means. +* Commands: VC Directory Commands. Commands to use in a VC directory buffer. +@end menu + +@node VC Directory Buffer +@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 -omitted; if all files in a directory are up-to-date, the directory is -omitted as well. (However, the directory in which @code{vc-dir} was -run will always be shown as @file{./}.) 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. +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 @@ -1043,7 +1024,7 @@ need to merge them with the work file before you can check it in. @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 nil (@pxref{CVS Options}). This is +@code{vc-cvs-stay-local}) is @code{nil} (@pxref{CVS Options}). 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 @@ -1064,10 +1045,6 @@ 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}. -@menu -* VC Directory Commands:: Commands to use in a VC directory buffer. -@end menu - @node VC Directory Commands @subsubsection VC Directory Commands @@ -1134,12 +1111,12 @@ 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 a set of files, -it requires that all of those files must be either in the same state or -in compatible states; otherwise it will throw an error (added, -modified and removed states are considered compatible). Note that 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 + 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 @@ -1365,6 +1342,7 @@ during this particular editing session. @node Change Log @section Change Logs +@cindex change log A change log file contains a chronological record of when and why you have changed a program, consisting of a sequence of entries describing individual changes. Normally it is kept in a file called @@ -1373,7 +1351,14 @@ one of its parent directories. A single @file{ChangeLog} file can record changes for all the files in its directory and all its subdirectories. -@cindex change log +@menu +* Change Log Commands:: Commands for editing change log files. +* Format of ChangeLog:: What the change log file looks like. +@end menu + +@node Change Log Commands +@subsection Change Log Commands + @kindex C-x 4 a @findex add-change-log-entry-other-window The Emacs command @kbd{C-x 4 a} adds a new entry to the change log @@ -1440,10 +1425,6 @@ insert a VC log entry into a Change Log buffer by typing @kbd{C-x v a} (@pxref{Change Logs and VC}). @end ifnottex -@menu -* Format of ChangeLog:: What the change log file looks like. -@end menu - @node Format of ChangeLog @subsection Format of ChangeLog