procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

; Improve documentation of VC commands

Browse source 
* doc/emacs/maintaining.texi (Basic VC Editing)
(VC With A Merging VCS, VC With A Locking VCS, Advanced C-x v v)
(Registering, Pulling / Pushing, Merging): Improve wording,
accuracy, and indexing.

* lisp/vc/vc.el (vc-next-action): Doc fix.
This commit is contained in:
Eli Zaretskii 2023-10-08 11:29:29 +03:00
parent 0590e3e69a
commit 81a0c1ed2e
2 changed files with 190 additions and 128 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

288
doc/emacs/maintaining.texi
View file

@ -481,22 +481,23 @@ system, but is usually not excessive.
@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
VC fileset is simply that one file. When you type them in a VC
collection of one or more files that a VC operation acts upon. 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}). Likewise,
when you invoke a VC command from a Dired buffer, the VC fileset
consists of the marked files (@pxref{Marks vs Flags}), defaulting to
the file shown on the current line if no files are marked.
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.
With modern changeset-based version control systems (@pxref{VCS
Changesets}), such as Git, Mercurial, and Bazaar, 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; thus, committing a fileset generates one revision for
each changed file in the fileset.
@table @kbd
@item C-x v v
@ -507,14 +508,16 @@ VC fileset.
@findex vc-next-action
@kindex 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
into it. The precise actions are described in detail in the following
subsections. You can use @kbd{C-x v v} either in a file-visiting
buffer, in a Dired buffer, or in a VC Directory buffer; in the latter
two cases the command operates on the fileset consisting of the marked
files.
(@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 into it.
The precise actions for each situation are described in detail in the
following subsections. You can use @kbd{C-x v v} either in a
file-visiting buffer, in a Dired buffer, or in a VC Directory buffer;
in the latter two cases the command operates on the fileset consisting
of the marked files. You can also use @kbd{C-x v v}, in a buffer with
patches under Diff Mode (@pxref{Diff Mode}), in which case the command
operates on the files whose diffs are shown in the buffer.
Note that VC filesets are distinct from the named filesets used
for viewing and visiting files in functional groups
@ -522,7 +525,7 @@ for viewing and visiting files in functional groups
and don't persist across sessions.
@menu
* VC With A Merging VCS:: Without locking: default mode for CVS.
* VC With A Merging VCS:: Without locking: default mode for Git, Hg, SVN, CVS.
* VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS.
* Advanced C-x v v:: Advanced features available with a prefix argument.
@end menu
@ -530,44 +533,56 @@ 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;
@pxref{VCS Merging}), @kbd{C-x v v} does the following:
With a modern merging-based version control system (such as Git and Hg;
@pxref{VCS Merging}), @kbd{C-x v v} does the following when invoked
from a buffer that visits a version-controlled file or a VC Directory
or Dired buffer:
@itemize @bullet
@item
If there is more than one file in the VC fileset and the files have
inconsistent version control statuses, signal an error. (Note,
however, that a fileset is allowed to include both newly-added
files and modified files; @pxref{Registering}.)
however, that a fileset is allowed to include both newly-added files
and modified files; @pxref{Registering}.) Also signal an error if the
files in the fileset are missing (removed from the filesystem, but
still tracked by version control), or are ignored by version control.
@item
If every file in the VC fileset is registered and unchanged with
respect to the last revision, do nothing.
@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. @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.
control system, register the newly-added files in the VC fileset,
i.e., place them 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.
You can also specify the system explicitly, see @ref{Advanced C-x v
v}. Note that registering the files doesn't commit them; you must
invoke @w{@kbd{C-x v v}} again to commit, see below.
@item
If every work file in the VC fileset is unchanged, do nothing.
If every file in the VC fileset has been either newly-added or
modified, commit the changed files. To do this, Emacs pops up a
@file{*vc-log*} buffer; type the desired log entry for the changes,
followed by @kbd{C-c C-c} to commit. @xref{Log Buffer}.
With modern decentralized version control systems (Git, Mercurial,
etc.), the changes are committed locally and not automatically
propagated to the upstream repository (which is usually on a remote
host). In these cases, if the repository has been changed since your
last update, the commit may fail. In that case, you must update from
upstream and then try again. Use @kbd{C-x v +} (@pxref{Pulling /
Pushing}) or @kbd{C-x v m} (@pxref{Merging}) for that.
With a centralized version control system, if the commit fails due to
upstream changes, type @kbd{C-x v v} again to merge in the upstream
repository changes.
@item
If every work file in the VC fileset has been modified, commit the
changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the
desired log entry for the new revision, followed by @kbd{C-c C-c} to
commit. @xref{Log Buffer}.
If committing to a shared repository, the commit may fail if the
repository has been changed since your last update. In that
case, you must perform an update before trying again. On a
decentralized version control system, use @kbd{C-x v +}
(@pxref{Pulling / Pushing}) or @kbd{C-x v m} (@pxref{Merging}).
On a centralized version control system, type @kbd{C-x v v} again to
merge in the repository changes.
@item
Finally, if you are using a centralized version control system, check
if each work file in the VC fileset is up-to-date. If any file has
been changed in the repository, offer to update it.
Finally, if you are using a centralized version control system, if any
file in the VC fileset is outdated with respect to the upstream
repository, offer to update the fileset from the repository.
@end itemize
These rules also apply when you use RCS in its non-locking mode,
@ -581,43 +596,60 @@ changes. In addition, locking is possible with RCS even in this mode:
@kbd{C-x v v} with an unmodified file locks the file, just as it does
with RCS in its normal locking mode (@pxref{VC With A Locking VCS}).
If @kbd{C-x v v} is invoked from a buffer under Diff Mode, the
command assumes the buffer holds a set of patches for one or more
files. It then applies the changes to the respective files and
commits the changes after popping up the @file{*vc-log*} buffer to
allow you to type a suitable commit log message.
@node VC With A Locking VCS
@subsubsection Basic Version Control with Locking
On a locking-based version control system (such as SCCS, and RCS in
With a locking-based version control system (such as SCCS, and RCS in
its default mode), @kbd{C-x v v} does the following:
@itemize @bullet
@item
If there is more than one file in the VC fileset and the files have
inconsistent version control statuses, signal an error.
inconsistent version control statuses, signal an error. Also signal
an error if the files in the fileset are missing (removed from the
filesystem, but still tracked by version control).
@item
If each file in the VC fileset is not registered with a version
control system, register the VC fileset. @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.
control system, register the newly-added files in the fileset.
@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. You can also specify the system
explicitly, see @ref{Advanced C-x v v}.
@item
If each file is registered and unlocked, lock it and make it writable,
so that you can begin to edit it.
If each file is registered and unlocked, check the files out: lock
each one and make it writable, so that you can begin to edit it.
@item
If each file is locked by you and contains changes, commit the
changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the
desired log entry for the new revision, followed by @kbd{C-c C-c} to
commit (@pxref{Log Buffer}).
If each file is locked by you and contains changes, commit (a.k.a.@:
``check-in'') the changes. To do this, Emacs pops up a
@file{*vc-log*} buffer; type the desired log entry for the new
revision, followed by @kbd{C-c C-c} to commit (@pxref{Log Buffer}).
@item
If each file is locked by you, but you have not changed it, release
the lock and make the file read-only again.
the lock and make the file read-only again. This undoes previous
check-out operation for files that were not changed since the
checkout.
@item
If each file is locked by another user, ask whether you want to
steal the lock. If you say yes, the file becomes locked by you,
and a warning message is sent to the user who had formerly locked the
file.
@item
If files in the fileset are unlocked, but have changes with respect to
their last revision, offer to claim the lock for each such file or to
revert the file to the last checked-in revision. (This situation is
exceptional and should not normally happen.)
@end itemize
These rules also apply when you use CVS in locking mode, except
@ -642,19 +674,21 @@ and Emacs fails to detect the correct one.
@item
Otherwise, if using CVS, RCS or SRC, 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
appropriate revision ID (@pxref{Branches}).
If the fileset is modified (or locked), this makes Emacs commit the
files with 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}})
checks out the latest (head) revision on the current branch.
If the fileset is unmodified (and unlocked), this checks out 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}}) checks out the latest (a.k.a.@: ``head'') revision on
the current branch.
This is silently ignored on a decentralized version control system.
Those systems do not let you specify your own revision IDs, nor do
they use the concept of checking out individual files.
Specifying revision ID in this manner is silently ignored by a
decentralized version control system. Those systems do not let you
specify your own revision IDs, nor do they use the concept of checking
out individual files.
@end itemize
@node Log Buffer
@ -788,17 +822,21 @@ If Emacs cannot find a version control system to register the file
under, it prompts for a repository type, creates a new repository, and
registers the file into that repository.
On most version control systems, registering a file with @kbd{C-x v
i} or @kbd{C-x v v} adds it to the working tree but not to the
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 a single
commit can include both file additions and edits to existing files.
@cindex added files, VC
@cindex files added to VCS
With most version control systems, registering a file with
@w{@kbd{C-x v i}} or @w{@kbd{C-x v v}} adds it to the working tree,
but does not commit it, i.e., doesn't add it to the repository. Such
files are labeled as @dfn{added} in the VC Directory buffer, and the
mode line of the buffers visiting such files shows a revision ID of
@samp{@@@@}. To make the registration take effect in the repository,
you must commit the newly-added files (@pxref{Basic VC Editing}).
Note that a single commit can include both file additions and edits to
files already known to the VCS.
On a locking-based version control system (@pxref{VCS Merging}),
With a locking-based version control system (@pxref{VCS Merging}),
registering a file leaves it unlocked and read-only. Type @kbd{C-x v
v} to start editing it.
v} to check-out the file and start editing it.
@node Old Revisions
@subsection Examining And Comparing Old Revisions
@ -1563,32 +1601,39 @@ commit will be committed to that specific branch.
@subsubsection Pulling/Pushing Changes into/from a Branch
@table @kbd
@cindex push changes to upstream (VC)
@item C-x v P
On a decentralized version control system, update another location
with changes from the current branch (a.k.a. ``push'' changes). This
concept does not exist for centralized version control systems
With a decentralized version control system, update another repository
with locally-committed changes from the current branch (a.k.a.@:
@dfn{push} changes). This concept does not exist for centralized
version control systems
@cindex pull changes from upstream (VC)
@item C-x v +
On a decentralized version control system, update the current branch
by ``pulling in'' changes from another location.
With a decentralized version control system, update the current branch
of the local repository by @dfn{pulling in} changes from another
repository.
On a centralized version control system, update the current VC
fileset.
With a centralized version control system, update the current VC
fileset from the repository.
@end table
@kindex C-x v P
@findex vc-push
@cindex upstream repository
On a decentralized version control system, the command @kbd{C-x v P}
(@code{vc-push}) updates another location with changes from the
(@code{vc-push}) updates another location, commonly known as the
@dfn{upstream repository}, with locally-committed changes from the
current branch. With a prefix argument, it prompts for the exact
version control command to run, which lets you specify where to push
changes; the default is @kbd{bzr push} with Bazaar, @kbd{git
push} with Git, and @kbd{hg push} with Mercurial. The default
commands always push to a default location determined by the version
control system from your branch configuration.
changes; the default is @kbd{bzr push} with Bazaar, @kbd{git push}
with Git, and @kbd{hg push} with Mercurial. The default commands
always push to the repository in the default location determined by
the version control system from your branch configuration.
Prior to pushing, you can use @kbd{C-x v O} (@code{vc-log-outgoing})
to view a log buffer of the changes to be sent. @xref{VC Change Log}.
to view a log buffer of the changes to be sent upstream. @xref{VC
Change Log}.
@cindex bound branch (Bazaar VCS)
This command is currently supported only by Bazaar, Git, and Mercurial.
@ -1602,13 +1647,15 @@ bound.
@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.
With a decentralized version control system, the command @kbd{C-x v
+} (@code{vc-pull}) updates the current branch of the local repository
and it working tree with changes made in the upstream repository. It
is typically used to update a copy (a.k.a.@: @dfn{clone}) 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 the repository in the
default location determined by the version control system from your
branch configuration.
Amongst decentralized version control systems, @kbd{C-x v +} is
currently supported only by Bazaar, Git, and Mercurial. With Bazaar,
@ -1624,7 +1671,7 @@ the working directory.
to view a log buffer of the changes to be applied. @xref{VC Change
Log}.
On a centralized version control system like CVS, @kbd{C-x v +}
With a centralized version control system like CVS, @kbd{C-x v +}
updates the current VC fileset from the repository.
@node Merging
@ -1633,36 +1680,36 @@ updates the current VC fileset from the repository.
@table @kbd
@item C-x v m
On a decentralized version control system, merge changes from another
With a decentralized version control system, merge changes from another
branch into the current one.
On a centralized version control system, merge changes from another
With 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.
trivial operation, as overlapping and conflicting 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 @kbd{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). With Mercurial, this prompts for argument
to pass to @kbd{hg merge}. The output from running the merge
command is shown in a separate buffer.
With a decentralized version control system, you merge changes with
the command @kbd{C-x v m} (@code{vc-merge}). With Bazaar, this
prompts for the exact arguments to pass to the @command{bzr merge}
command, offering a sensible default if possible. With Git, this
prompts for the name of a branch to merge from, with completion (based
on the branch names known to the current repository). With Mercurial,
this prompts for argument to pass to @command{hg merge}. 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}
With 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 @kbd{@key{RET}}, Emacs simply
merges any changes that were made on the same branch since you checked
the file out.
the current VC fileset. If you just type @kbd{@key{RET}} at the
prompt, Emacs simply merges any changes that were made on the same
branch since you checked the file out.
@cindex conflicts
@cindex conflicts, VC
@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
@ -1671,9 +1718,12 @@ 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}).
resolve the conflict by editing the conflicted files; by default,
Emacs will place buffers with VC conflicts in the special Smerge mode,
which provides special commands for resolving the merge conflicts.
Once you are done with resolving the conflicts and have saved the
files with resolved conflicts, those 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

30
lisp/vc/vc.el
View file

@ -1222,18 +1222,23 @@ BEWARE: this function may change the current buffer."
(defun vc-next-action (verbose)
"Do the next logical version control operation on the current fileset.
This requires that all files in the current VC fileset be in the
same state. If not, signal an error.
same state. If they are not, signal an error. Also signal an error if
files in the fileset are missing (removed, but tracked by version control),
or are ignored by the version control system.
For merging-based version control systems:
If every file in the VC fileset is not registered for version
control, register the fileset (but don't commit).
If every work file in the VC fileset is added or changed, pop
up a *vc-log* buffer to commit the fileset.
For modern merging-based version control systems:
If every file in the fileset is not registered for version
control, register the fileset (but don't commit). If VERBOSE is
non-nil (interactively, the prefix argument), ask for the VC
backend with which to register the fileset.
If every work file in the VC fileset is either added or modified,
pop up a *vc-log* buffer to commit the fileset changes.
For a centralized version control system, if any work file in
the VC fileset is out of date, offer to update the fileset.
For old-style locking-based version control systems, like RCS:
If every file is not registered, register the file(s).
If every file is not registered, register the file(s); with a prefix
argument, allow to specify the VC backend for registration.
If every file is registered and unlocked, check out (lock)
the file(s) for editing.
If every file is locked by you and has changes, pop up a
@ -1241,14 +1246,21 @@ For old-style locking-based version control systems, like RCS:
read-only copy of each changed file after checking in.
If every file is locked by you and unchanged, unlock them.
If every file is locked by someone else, offer to steal the lock.
If files are unlocked, but have changes, offer to either claim the
lock or revert to the last checked-in version.
If this command is invoked from a patch buffer under `diff-mode', it
will apply the diffs from the patch and pop up a *vc-log* buffer to
check-in the resulting changes.
When using this command to register a new file (or files), it
will automatically deduce which VC repository to register it
with, using the most specific one.
If VERBOSE is non-nil (interactively, the prefix argument),
you can specify a VC backend or (for centralized VCS only)
the revision ID or branch ID."
you can specify another VC backend for the file(s),
or (for centralized VCS only) the revision ID or branch ID
from which to check out the file(s)."
(interactive "P")
(let* ((vc-fileset (vc-deduce-fileset nil t 'state-model-only-files))
(backend (car vc-fileset))