X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/36a305a723c63fd345be65c536c52fe9765c14be..64a6f1f30ee1ce0de37ad1010b49ea84dca16853:/doc/emacs/maintaining.texi diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index d21e3af83d..e066c491ac 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1,6 +1,6 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012 -@c Free Software Foundation, Inc. +@c This is part of the Emacs manual., Abbrevs, This is part of the Emacs manual., Top +@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2014 Free Software +@c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Maintaining @chapter Maintaining Large Programs @@ -31,7 +31,7 @@ versions of a source file, storing information such as the creation time of each version, who made it, and a description of what was changed. - The Emacs version control interface is called @dfn{VC}. VC commands + The Emacs version control interface is called @dfn{VC}@. VC commands work with several different version control systems; currently, it supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS, SCCS/CSSC, and Subversion. Of these, the GNU project distributes CVS, @@ -56,6 +56,7 @@ variable @code{vc-handled-backends} to @code{nil} * Old Revisions:: Examining and comparing old versions. * VC Change Log:: Viewing the VC Change Log. * VC Undo:: Canceling changes before or after committing. +* VC Ignore:: Ignore files under version control system. * VC Directory Mode:: Listing files managed by version control. * Branches:: Multiple lines of development. @ifnottex @@ -73,8 +74,8 @@ provides a uniform interface for common operations in many version control operations. Some uncommon or intricate version control operations, such as -altering repository settings, are not supported in VC. You should -perform such tasks outside Emacs, e.g.@: via the command line. +altering repository settings, are not supported in VC@. You should +perform such tasks outside Emacs, e.g., via the command line. This section provides a general overview of version control, and describes the version control systems that VC supports. You can skip @@ -128,13 +129,13 @@ which it refers to as @dfn{back ends}: @item SCCS was the first version control system ever built, and was long ago superseded by more advanced ones. VC compensates for certain features -missing in SCCS (e.g.@: tag names for releases) by implementing them +missing in SCCS (e.g., tag names for releases) by implementing them itself. Other VC features, such as multiple branches, are simply unavailable. Since SCCS is non-free, we recommend avoiding it. @cindex CSSC @item -CSSC is a free replacement for SCCS. You should use CSSC only if, for +CSSC is a free replacement for SCCS@. You should use CSSC only if, for some reason, you cannot use a more recent and better-designed version control system. @@ -342,7 +343,9 @@ before version control systems. 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. +single directory separately from those of other directories. Another +advantage is that commit logs can't be fixed in many version control +systems. 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 @@ -377,7 +380,7 @@ 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 +was removed from the version control. Finally, @samp{?} means that the file is under version control, but is missing from the working tree. @@ -455,7 +458,7 @@ and don't persist across sessions. @node VC With A Merging VCS @subsubsection Basic Version Control with Merging - On a merging-based version control system (i.e.@: most modern ones; + On a merging-based version control system (i.e., most modern ones; @pxref{VCS Merging}), @kbd{C-x v v} does the following: @itemize @bullet @@ -467,7 +470,7 @@ files and ``modified'' files; @pxref{Registering}.) @item If none of the files in the VC fileset are registered with a version -control system, register the VC fileset, i.e.@: place it under version +control system, register the VC fileset, i.e., place it under version control. @xref{Registering}. If Emacs cannot find a system to register under, it prompts for a repository type, creates a new repository, and registers the VC fileset with it. @@ -568,13 +571,13 @@ and Emacs fails to detect the correct one. Otherwise, if using CVS or RCS, you can specify a revision ID. If the fileset is modified (or locked), this makes Emacs commit with -that revision ID. You can create a new branch by supplying an +that revision ID@. You can create a new branch by supplying an appropriate revision ID (@pxref{Branches}). If the fileset is unmodified (and unlocked), this checks the specified revision into the working tree. You can also specify a revision on another branch by giving its revision or branch ID (@pxref{Switching -Branches}). An empty argument (i.e.@: @kbd{C-u C-x v v @key{RET}}) +Branches}). An empty argument (i.e., @kbd{C-u C-x v v @key{RET}}) checks out the latest (``head'') revision on the current branch. This signals an error on a decentralized version control system. @@ -596,6 +599,7 @@ the buffer and commit the change, together with your log entry. @cindex Log Edit mode @cindex mode, Log Edit @vindex vc-log-mode-hook +@c FIXME: Mention log-edit-mode-hook here? --xfq The major mode for the @file{*vc-log*} buffer is Log Edit mode, a variant of Text mode (@pxref{Text Mode}). On entering Log Edit mode, Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook} @@ -649,7 +653,7 @@ opposite way of 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 + To abort a commit, just @emph{don't} type @kbd{C-c C-c} in that buffer. You can switch buffers and do other editing. As long as you don't try to make another commit, the entry you were editing remains in the @file{*vc-log*} buffer, and you can go back to that buffer at @@ -759,7 +763,7 @@ comparison again, generating a new diff. prompts for two revision IDs (@pxref{VCS Concepts}), and displays a diff between those versions of the fileset. This will not work reliably for multi-file VC filesets, if the version control system is -file-based rather than changeset-based (e.g.@: CVS), since then +file-based rather than changeset-based (e.g., CVS), since then revision IDs for different files would not be related in any meaningful way. @@ -783,7 +787,7 @@ Ediff session. @xref{Top,, Ediff, ediff, The Ediff Manual}. @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 the changes in the entire current working tree (i.e.@: the +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. @@ -795,7 +799,7 @@ 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 relevant version control system, -e.g.@: @code{bzr} for Bazaar. Since @code{nil} means to check the +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}, @@ -835,12 +839,12 @@ view diffs, or view log entries: @table @kbd @item p -Annotate the previous revision, i.e.@: the revision before the one +Annotate the previous revision, i.e., the revision before the one currently annotated. A numeric prefix argument is a repeat count, so @kbd{C-u 10 p} would take you back 10 revisions. @item n -Annotate the next revision, i.e.@: the revision after the one +Annotate the next revision, i.e., the revision after the one currently annotated. A numeric prefix argument is a repeat count. @item j @@ -986,7 +990,7 @@ earlier revision. This shows the changes to all files made in that revision. @item @key{RET} -In a compact-style log buffer (e.g.@: the one created by @kbd{C-x v +In a compact-style log buffer (e.g., the one created by @kbd{C-x v L}), toggle between showing and hiding the full log entry for the revision at point. @end table @@ -1030,6 +1034,25 @@ 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 Ignore +@subsection Ignore Version Control Files + +@table @kbd +@item C-x v G +Ignore a file under current version control system. (@code{vc-ignore}). +@end table + +@kindex C-x v G +@findex vc-ignore + Many source trees contain some files that do not need to be +versioned, such as editor backups, object or bytecode files, and built +programs. You can simply not add them, but then they'll always crop +up as unknown files. You can also tell the version control system to +ignore these files by adding them to the ignore file at the top of the +tree. @kbd{C-x v G} (@code{vc-ignore}) can help you do this. When +called with a prefix argument, you can remove a file from the ignored +file list. + @node VC Directory Mode @subsection VC Directory Mode @@ -1064,8 +1087,8 @@ the version control system which the VC Directory buffer should use. @pindex cvs @cindex CVS directory mode 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}. +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 @@ -1080,7 +1103,7 @@ PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to 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 +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. @@ -1131,7 +1154,7 @@ 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 +necessary, e.g., when doing a commit). This may be desirable if you are working offline or the network is slow. @end ifnottex @@ -1201,7 +1224,8 @@ files and directories. @item x Hide files with @samp{up-to-date} status -(@code{vc-dir-hide-up-to-date}). +(@code{vc-dir-hide-up-to-date}). With a prefix argument, hide items +whose state is that of the item at point. @end table @findex vc-dir-mark @@ -1219,7 +1243,7 @@ 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}. +@kbd{i}, @kbd{D}, @kbd{L}, @kbd{G}, @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} @@ -1264,10 +1288,10 @@ bring them back at a later time). @cindex branch (version control) 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. +of development, which are called @dfn{branches}. Amongst other +things, branches can be 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 @@ -1307,7 +1331,7 @@ 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. +(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. @@ -1589,7 +1613,7 @@ source files. To produce a tags table, you run the @command{etags} shell command on a document or the source code file. The @samp{etags} program writes the tags to a @dfn{tags table file}, or @dfn{tags file} in -short. The conventional name for a tags file is @file{TAGS}. +short. The conventional name for a tags file is @file{TAGS}@. @xref{Create Tags Table}. Emacs provides many commands for searching and replacing using the @@ -1676,9 +1700,11 @@ specifies (using Bourne shell syntax) that the commands @item In Lisp code, any function defined with @code{defun}, any variable -defined with @code{defvar} or @code{defconst}, and in general the first -argument of any expression that starts with @samp{(def} in column zero is -a tag. +defined with @code{defvar} or @code{defconst}, and in general the +first argument of any expression that starts with @samp{(def} in +column zero is a tag. As an exception, expressions of the form +@code{(defvar @var{foo})} are treated as declarations, and are only +tagged if the @samp{--declarations} option is given. @item In Scheme code, tags include anything defined with @code{def} or with a @@ -1696,9 +1722,9 @@ tags. Use the @samp{--packages-only} option to create tags for packages only. In Ada, the same name can be used for different kinds of entity -(e.g.@:, for a procedure and for a function). Also, for things like -packages, procedures and functions, there is the spec (i.e.@: the -interface) and the body (i.e.@: the implementation). To make it +(e.g., for a procedure and for a function). Also, for things like +packages, procedures and functions, there is the spec (i.e., the +interface) and the body (i.e., the implementation). To make it easier to pick the definition you want, Ada tag name have suffixes indicating the type of entity: @@ -1766,11 +1792,11 @@ the file. @item In Perl code, the tags are the packages, subroutines and variables -defined by the @code{package}, @code{sub}, @code{my} and @code{local} -keywords. Use @samp{--globals} if you want to tag global variables. -Tags for subroutines are named @samp{@var{package}::@var{sub}}. The -name for subroutines defined in the default package is -@samp{main::@var{sub}}. +defined by the @code{package}, @code{sub}, @code{use constant}, +@code{my}, and @code{local} keywords. Use @samp{--globals} if you +want to tag global variables. Tags for subroutines are named +@samp{@var{package}::@var{sub}}. The name for subroutines defined in +the default package is @samp{main::@var{sub}}. @item In PHP code, tags are functions, classes and defines. Vars are tags @@ -2221,7 +2247,7 @@ the current buffer, followed by the remaining files of the tags table. reads a regexp to search for and a string to replace with, just like ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x tags-search}, but repeatedly, processing matches according to your -input. @xref{Replace}, for more information on query replace. +input. @xref{Query Replace}, for more information on query replace. @vindex tags-case-fold-search @cindex case-sensitivity and tags search @@ -2341,7 +2367,7 @@ directory trees. The @dfn{project root} is the topmost directory of a project. To define a new project, visit a file in the desired project root and type @kbd{M-x ede-new}. This command prompts for a @dfn{project type}, which refers to the underlying method that EDE -will use to manage the project (@pxref{Creating a Project, EDE,, ede, +will use to manage the project (@pxref{Creating a project, EDE,, ede, Emacs Development Environment}). The most common project types are @samp{Make}, which uses Makefiles, and @samp{Automake}, which uses GNU Automake (@pxref{Top, Automake,, automake, Automake}). In both cases,