Snapshot primitives globally renamed to refer to tags, documentation updated.

10 files changed, 123 insertions, 121 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 96f0d611113..6504f1cfdbf 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,10 @@
 2008-05-15  Eric S. Raymond  <esr@snark.thyrsus.com>
 
+        * vc-cvs.el, vc-git.el, vc-hg.el, vc-hooks.el, vc-mcvs.el,
+        vc-rcs.el, vc-sccs.el, vc-svn.el, vc.el: Rename
+        vc-*-create-snapshot and vc-*-retrieve-snapshot to vc-*-create-tag
+        and vc-*-retireve-tag respectively.
+
         * vc-dispatcher.el: Fix an incorrect buffer name and remove an
         unneeded defalias.
 
diff --git a/lisp/vc-cvs.el b/lisp/vc-cvs.el
index 41372debcf0..90a6b7b2e1f 100644
--- a/lisp/vc-cvs.el
+++ b/lisp/vc-cvs.el
@@ -622,19 +622,19 @@ systime, or nil if there is none."
       nil)))
 
 ;;;
-;;; Snapshot system
+;;; Tag system
 ;;;
 
-(defun vc-cvs-create-snapshot (dir name branchp)
+(defun vc-cvs-create-tag (dir name branchp)
   "Assign to DIR's current revision a given NAME.
 If BRANCHP is non-nil, the name is created as a branch (and the current
 workspace is immediately moved to that new branch)."
   (vc-cvs-command nil 0 dir "tag" "-c" (if branchp "-b") name)
   (when branchp (vc-cvs-command nil 0 dir "update" "-r" name)))
 
-(defun vc-cvs-retrieve-snapshot (dir name update)
-  "Retrieve a snapshot at and below DIR.
-NAME is the name of the snapshot; if it is empty, do a `cvs update'.
+(defun vc-cvs-retrieve-tag (dir name update)
+  "Retrieve a tag at and below DIR.
+NAME is the name of the tag; if it is empty, do a `cvs update'.
 If UPDATE is non-nil, then update (resynch) any affected buffers."
   (with-current-buffer (get-buffer-create "*vc*")
     (let ((default-directory dir)
diff --git a/lisp/vc-git.el b/lisp/vc-git.el
index b4704efc61e..4a5b7ab8403 100644
--- a/lisp/vc-git.el
+++ b/lisp/vc-git.el
@@ -43,37 +43,39 @@
 ;; beginning of vc.el. The current status is:
 ;; ("??" means: "figure out what to do about it")
 ;;
-;; FUNCTION NAME                                   STATUS
+;; FUNCTION NAME                        STATUS
 ;; BACKEND PROPERTIES
-;; * revision-granularity                          OK
+;; * revision-granularity                      OK
 ;; STATE-QUERYING FUNCTIONS
-;; * registered (file)                             OK
+;; * registered (file)                     OK
 ;; * state (file)                                  OK
 ;; - state-heuristic (file)                        NOT NEEDED
-;; * working-revision (file)                       OK
-;; - latest-on-branch-p (file)                     NOT NEEDED
-;; * checkout-model (files)                        OK
+;; * working-revision (file)               OK
+;; - latest-on-branch-p (file)             NOT NEEDED
+;; * checkout-model (files)                OK
 ;; - workfile-unchanged-p (file)                   OK
 ;; - mode-line-string (file)                       OK
-;; - prettify-state-info (file)                    OK
+;; - prettify-state-info (file)            OK
 ;; STATE-CHANGING FUNCTIONS
-;; * create-repo ()                                OK
-;; * register (files &optional rev comment)        OK
+;; * create-repo ()                        OK
+;; * register (files &optional rev comment)    OK
 ;; - init-revision (file)                          NOT NEEDED
 ;; - responsible-p (file)                          OK
 ;; - could-register (file)                         NOT NEEDED, DEFAULT IS GOOD
 ;; - receive-file (file rev)                       NOT NEEDED
-;; - unregister (file)                             OK
+;; - unregister (file)                     OK
 ;; * checkin (files rev comment)                   OK
 ;; * find-revision (file rev buffer)               OK
 ;; * checkout (file &optional editable rev)        OK
 ;; * revert (file &optional contents-done)         OK
-;; - rollback (files)                              COULD BE SUPPORTED
-;; - merge (file rev1 rev2)                        It would be possible to merge changes into
-;;                                                 a single file, but when committing they
-;;                                                 wouldn't be identified as a merge by git,
-;;                                                 so it's probably not a good idea.
-;; - merge-news (file)                             see `merge'
+;; - rollback (files)                      COULD BE SUPPORTED
+;; - merge (file rev1 rev2)                   It would be possible to merge
+;;                                          changes into a single file, but when
+;;                                          committing they wouldn't
+;;                                          be identified as a merge
+;;                                          by git, so it's probably
+;;                                          not a good idea.
+;; - merge-news (file)                     see `merge'
 ;; - steal-lock (file &optional revision)          NOT NEEDED
 ;; HISTORY FUNCTIONS
 ;; * print-log (files &optional buffer)            OK
@@ -81,27 +83,26 @@
 ;; - show-log-entry (revision)                     OK
 ;; - comment-history (file)                        ??
 ;; - update-changelog (files)                      COULD BE SUPPORTED
-;; * diff (file &optional rev1 rev2 buffer)        OK
+;; * diff (file &optional rev1 rev2 buffer)                OK
 ;; - revision-completion-table (files)             OK
 ;; - annotate-command (file buf &optional rev)     OK
 ;; - annotate-time ()                              OK
 ;; - annotate-current-time ()                      NOT NEEDED
-;; - annotate-extract-revision-at-line ()          OK
-;; SNAPSHOT SYSTEM
-;; - create-snapshot (dir name branchp)            OK
-;; - assign-name (file name)                       NOT NEEDED
-;; - retrieve-snapshot (dir name update)           OK, needs to update buffers
+;; - annotate-extract-revision-at-line ()                  OK
+;; TAG SYSTEM
+;; - create-tag (dir name branchp)         OK
+;; - retrieve-tag (dir name update)        OK, needs to update buffers
 ;; MISCELLANEOUS
-;; - make-version-backups-p (file)                 NOT NEEDED
-;; - repository-hostname (dirname)                 NOT NEEDED
+;; - make-version-backups-p (file)         NOT NEEDED
+;; - repository-hostname (dirname)         NOT NEEDED
 ;; - previous-revision (file rev)                  OK
-;; - next-revision (file rev)                      OK
-;; - check-headers ()                              COULD BE SUPPORTED
-;; - clear-headers ()                              NOT NEEDED
-;; - delete-file (file)                            OK
-;; - rename-file (old new)                         OK
-;; - find-file-hook ()                             NOT NEEDED
-;; - find-file-not-found-hook ()                   NOT NEEDED
+;; - next-revision (file rev)              OK
+;; - check-headers ()                      COULD BE SUPPORTED
+;; - clear-headers ()                      NOT NEEDED
+;; - delete-file (file)                    OK
+;; - rename-file (old new)                 OK
+;; - find-file-hook ()                     NOT NEEDED
+;; - find-file-not-found-hook ()                NOT NEEDED
 
 (eval-when-compile
   (require 'cl)
@@ -554,16 +555,16 @@ or BRANCH^ (where \"^\" can be repeated)."
     (and (looking-at "[0-9a-f^][0-9a-f]+")
          (buffer-substring-no-properties (match-beginning 0) (match-end 0)))))
 
-;;; SNAPSHOT SYSTEM
+;;; TAG SYSTEM
 
-(defun vc-git-create-snapshot (dir name branchp)
+(defun vc-git-create-tag (dir name branchp)
   (let ((default-directory dir))
     (and (vc-git-command nil 0 nil "update-index" "--refresh")
          (if branchp
              (vc-git-command nil 0 nil "checkout" "-b" name)
            (vc-git-command nil 0 nil "tag" name)))))
 
-(defun vc-git-retrieve-snapshot (dir name update)
+(defun vc-git-retrieve-tag (dir name update)
   (let ((default-directory dir))
     (vc-git-command nil 0 nil "checkout" name)
     ;; FIXME: update buffers if `update' is true
diff --git a/lisp/vc-hg.el b/lisp/vc-hg.el
index baa60589f9a..6b025c8cfa7 100644
--- a/lisp/vc-hg.el
+++ b/lisp/vc-hg.el
@@ -76,10 +76,9 @@
 ;; - annotate-time ()                          OK
 ;; - annotate-current-time ()                  NOT NEEDED
 ;; - annotate-extract-revision-at-line ()      OK
-;; SNAPSHOT SYSTEM
-;; - create-snapshot (dir name branchp)        NEEDED (probably branch?)
-;; - assign-name (file name)                   NOT NEEDED
-;; - retrieve-snapshot (dir name update)       ?? NEEDED??
+;; TAG SYSTEM
+;; - create-tag (dir name branchp)       NEEDED
+;; - retrieve-tag (dir name update)       NEEDED
 ;; MISCELLANEOUS
 ;; - make-version-backups-p (file)             ??
 ;; - repository-hostname (dirname)             ??
diff --git a/lisp/vc-hooks.el b/lisp/vc-hooks.el
index ed44eba3498..738cf257562 100644
--- a/lisp/vc-hooks.el
+++ b/lisp/vc-hooks.el
@@ -981,8 +981,8 @@ Used in `find-file-not-found-functions'."
     (define-key map "i" 'vc-register)
     (define-key map "l" 'vc-print-log)
     (define-key map "m" 'vc-merge)
-    (define-key map "r" 'vc-retrieve-snapshot)
-    (define-key map "s" 'vc-create-snapshot)
+    (define-key map "r" 'vc-retrieve-tag)
+    (define-key map "s" 'vc-create-tag)
     (define-key map "u" 'vc-revert)
     (define-key map "v" 'vc-next-action)
     (define-key map "+" 'vc-update)
@@ -996,12 +996,12 @@ Used in `find-file-not-found-functions'."
   (let ((map (make-sparse-keymap "Version Control")))
     ;;(define-key map [show-files]
     ;;  '("Show Files under VC" . (vc-directory t)))
-    (define-key map [vc-retrieve-snapshot]
-      '(menu-item "Retrieve Snapshot" vc-retrieve-snapshot
-                  :help "Retrieve snapshot"))
-    (define-key map [vc-create-snapshot]
-      '(menu-item "Create Snapshot" vc-create-snapshot
-                  :help "Create Snapshot"))
+    (define-key map [vc-retrieve-tag]
+      '(menu-item "Retrieve Tag" vc-retrieve-tag
+                  :help "Retrieve tagged version or branch"))
+    (define-key map [vc-create-tag]
+      '(menu-item "Create Tag" vc-create-tag
+                  :help "Create version tag"))
     (define-key map [separator1] '("----"))
     (define-key map [vc-annotate]
       '(menu-item "Annotate" vc-annotate
diff --git a/lisp/vc-mcvs.el b/lisp/vc-mcvs.el
index dfe3bb1d1f9..32c7b99b41b 100644
--- a/lisp/vc-mcvs.el
+++ b/lisp/vc-mcvs.el
@@ -48,7 +48,7 @@
 
 ;;; Bugs:
 
-;; - Retrieving snapshots doesn't filter `cvs update' output and thus
+;; - Retrieving tags doesn't filter `cvs update' output and thus
 ;;   parses bogus filenames.  Don't know if it harms.
 
 ;;; Code:
@@ -461,10 +461,10 @@ Optional arg REVISION is a revision to annotate from."
 (defalias 'vc-mcvs-annotate-time 'vc-cvs-annotate-time)
 
 ;;;
-;;; Snapshot system
+;;; Tag system
 ;;;
 
-(defun vc-mcvs-create-snapshot (dir name branchp)
+(defun vc-mcvs-create-tag (dir name branchp)
   "Assign to DIR's current revision a given NAME.
 If BRANCHP is non-nil, the name is created as a branch (and the current
 workspace is immediately moved to that new branch)."
@@ -473,9 +473,9 @@ workspace is immediately moved to that new branch)."
     (vc-mcvs-command nil 0 dir "branch" name)
     (vc-mcvs-command nil 0 dir "switch" name)))
 
-(defun vc-mcvs-retrieve-snapshot (dir name update)
-  "Retrieve a snapshot at and below DIR.
-NAME is the name of the snapshot; if it is empty, do a `cvs update'.
+(defun vc-mcvs-retrieve-tag (dir name update)
+  "Retrieve a tag at and below DIR.
+NAME is the name of the tag; if it is empty, do a `cvs update'.
 If UPDATE is non-nil, then update (resynch) any affected buffers."
   (with-current-buffer (get-buffer-create "*vc*")
     (let ((default-directory dir)
diff --git a/lisp/vc-rcs.el b/lisp/vc-rcs.el
index 14a091c4a6f..bda6aec95c2 100644
--- a/lisp/vc-rcs.el
+++ b/lisp/vc-rcs.el
@@ -787,12 +787,19 @@ systime, or nil if there is none.  Also, reposition point."
 
 
 ;;;
-;;; Snapshot system
+;;; Tag system
 ;;;
 
-(defun vc-rcs-assign-name (file name)
-  "Assign to FILE's latest version a given NAME."
-  (vc-do-command "*vc*" 0 "rcs" (vc-name file) (concat "-n" name ":")))
+(defun vc-rcs-create-tag (backend dir name branchp)
+  (when branchp
+    (error "RCS backend %s does not support module branches."))
+  (let ((result (vc-tag-precondition dir)))
+    (if (stringp result)
+        (error "File %s is not up-to-date" result)
+      (vc-file-tree-walk
+       dir
+       (lambda (f)
+         (vc-do-command "*vc*" 0 "rcs" (vc-name f) (concat "-n" name ":")))))))
 
 
 ;;;
diff --git a/lisp/vc-sccs.el b/lisp/vc-sccs.el
index f8a98f52702..a5096da9643 100644
--- a/lisp/vc-sccs.el
+++ b/lisp/vc-sccs.el
@@ -352,12 +352,20 @@ revert all subfiles."
 
 
 ;;;
-;;; Snapshot system
+;;; Tag system.  SCCS doesn't have tags, so we simulate them by maintaining
+;;; our own set of name-to-revision mappings.
 ;;;
 
-(defun vc-sccs-assign-name (file name)
-  "Assign to FILE's latest revision a given NAME."
-  (vc-sccs-add-triple name file (vc-working-revision file)))
+(defun vc-sccs-create-tag (backend dir name branchp)
+  (when branchp
+    (error "SCCS backend %s does not support module branches."))
+  (let ((result (vc-tag-precondition dir)))
+    (if (stringp result)
+        (error "File %s is not up-to-date" result)
+      (vc-file-tree-walk
+       dir
+       (lambda (f)
+         (vc-sccs-add-triple name f (vc-working-revision f)))))))
 
 
 ;;;
@@ -373,7 +381,7 @@ revert all subfiles."
 (defun vc-sccs-rename-file (old new)
   ;; Move the master file (using vc-rcs-master-templates).
   (vc-rename-master (vc-name old) new vc-sccs-master-templates)
-  ;; Update the snapshot file.
+  ;; Update the tag file.
   (with-current-buffer
       (find-file-noselect
        (expand-file-name vc-sccs-name-assoc-file
@@ -446,7 +454,7 @@ The result is a list of the form ((REVISION . USER) (REVISION . USER) ...)."
     (kill-buffer (current-buffer))))
 
 (defun vc-sccs-lookup-triple (file name)
-  "Return the numeric revision corresponding to a named snapshot of FILE.
+  "Return the numeric revision corresponding to a named tag of FILE.
 If NAME is nil or a revision number string it's just passed through."
   (if (or (null name)
           (let ((firstchar (aref name 0)))
diff --git a/lisp/vc-svn.el b/lisp/vc-svn.el
index 44f7e8eb44d..0b0828ac23d 100644
--- a/lisp/vc-svn.el
+++ b/lisp/vc-svn.el
@@ -465,20 +465,20 @@ or svn+ssh://."
         (buffer-size (get-buffer buffer)))))
 
 ;;;
-;;; Snapshot system
+;;; Tag system
 ;;;
 
-(defun vc-svn-create-snapshot (dir name branchp)
+(defun vc-svn-create-tag (dir name branchp)
   "Assign to DIR's current revision a given NAME.
 If BRANCHP is non-nil, the name is created as a branch (and the current
 workspace is immediately moved to that new branch).
 NAME is assumed to be a URL."
   (vc-svn-command nil 0 dir "copy" name)
-  (when branchp (vc-svn-retrieve-snapshot dir name nil)))
+  (when branchp (vc-svn-retrieve-tag dir name nil)))
 
-(defun vc-svn-retrieve-snapshot (dir name update)
-  "Retrieve a snapshot at and below DIR.
-NAME is the name of the snapshot; if it is empty, do a `svn update'.
+(defun vc-svn-retrieve-tag (dir name update)
+  "Retrieve a tag at and below DIR.
+NAME is the name of the tag; if it is empty, do a `svn update'.
 If UPDATE is non-nil, then update (resynch) any affected buffers.
 NAME is assumed to be a URL."
   (vc-svn-command nil 0 dir "switch" name)
diff --git a/lisp/vc.el b/lisp/vc.el
index 7f355a6c38a..57f8f092d0e 100644
--- a/lisp/vc.el
+++ b/lisp/vc.el
@@ -438,28 +438,23 @@
 ;;   corresponding to the current line, or nil if there is no revision
 ;;   corresponding to the current line.
 ;;
-;; SNAPSHOT SYSTEM
+;; TAG SYSTEM
 ;;
-;; - create-snapshot (dir name branchp)
+;; - create-tag (dir name branchp)
 ;;
-;;   Take a snapshot of the current state of files under DIR and name it
-;;   NAME.  This should make sure that files are up-to-date before
-;;   proceeding with the action.  DIR can also be a file and if BRANCHP
-;;   is specified, NAME should be created as a branch and DIR should be
-;;   checked out under this new branch.  The default implementation does
-;;   not support branches but does a sanity check, a tree traversal and
-;;   for each file calls `assign-name'.
+;;   Attach the tag NAME to the state of the working copy.  This
+;;   should make sure that files are up-to-date before proceeding with
+;;   the action.  DIR can also be a file and if BRANCHP is specified,
+;;   NAME should be created as a branch and DIR should be checked out
+;;   under this new branch.  The default implementation does not
+;;   support branches but does a sanity check, a tree traversal and
+;;   assigns the tag to each file.
 ;;
-;; - assign-name (file name)
+;; - retrieve-tag (dir name update)
 ;;
-;;   Give name NAME to the working revision of FILE, assuming it is
-;;   up-to-date.  Only used by the default version of `create-snapshot'.
-;;
-;; - retrieve-snapshot (dir name update)
-;;
-;;   Retrieve a named snapshot of all registered files at or below DIR.
+;;   Retrieve the version tagged by NAME of all registered files at or below DIR.
 ;;   If UPDATE is non-nil, then update buffers of any files in the
-;;   snapshot that are currently visited.  The default implementation
+;;   tag that are currently visited.  The default implementation
 ;;   does a sanity check whether there aren't any uncommitted changes at
 ;;   or below DIR, and then performs a tree walk, using the `checkout'
 ;;   function to retrieve the corresponding revisions.
@@ -570,8 +565,6 @@
 ;;
 ;;;; Improved branch and tag handling:
 ;;
-;; - "snapshots" should be renamed to "tags", and thoroughly reworked.
-;;
 ;; - add a generic mechanism for remembering the current branch names,
 ;;   display the branch name in the mode-line. Replace
 ;;   vc-cvs-sticky-tag with that.
@@ -580,7 +573,7 @@
 ;;   adapted accordingly.  Also, it considers RCS and CVS to be the same, 
 ;;   which is pretty confusing.
 ;;
-;; - vc-create-snapshot and vc-retrieve-snapshot should update the
+;; - vc-create-tag and vc-retrieve-tag should update the
 ;;   buffers that might be visiting the affected files.
 ;;
 ;;;; Default Behavior:
@@ -2047,10 +2040,10 @@ outside of VC) and one wants to do some operation on it."
 
 ;; Named-configuration entry points
 
-(defun vc-snapshot-precondition (dir)
+(defun vc-tag-precondition (dir)
   "Scan the tree below DIR, looking for files not up-to-date.
 If any file is not up-to-date, return the name of the first such file.
-\(This means, neither snapshot creation nor retrieval is allowed.\)
+\(This means, neither tag creation nor retrieval is allowed.\)
 If one or more of the files are currently visited, return `visited'.
 Otherwise, return nil."
   (let ((status nil))
@@ -2063,40 +2056,40 @@ Otherwise, return nil."
       status)))
 
 ;;;###autoload
-(defun vc-create-snapshot (dir name branchp)
-  "Descending recursively from DIR, make a snapshot called NAME.
+(defun vc-create-tag (dir name branchp)
+  "Descending recursively from DIR, make a tag called NAME.
 For each registered file, the working revision becomes part of
 the named configuration.  If the prefix argument BRANCHP is
-given, the snapshot is made as a new branch and the files are
+given, the tag is made as a new branch and the files are
 checked out in that new branch."
   (interactive
    (list (read-file-name "Directory: " default-directory default-directory t)
-         (read-string "New snapshot name: ")
+         (read-string "New tag name: ")
          current-prefix-arg))
-  (message "Making %s... " (if branchp "branch" "snapshot"))
+  (message "Making %s... " (if branchp "branch" "tag"))
   (when (file-directory-p dir) (setq dir (file-name-as-directory dir)))
   (vc-call-backend (vc-responsible-backend dir)
-                   'create-snapshot dir name branchp)
-  (message "Making %s... done" (if branchp "branch" "snapshot")))
+                   'create-tag dir name branchp)
+  (message "Making %s... done" (if branchp "branch" "tag")))
 
 ;;;###autoload
-(defun vc-retrieve-snapshot (dir name)
-  "Descending recursively from DIR, retrieve the snapshot called NAME.
+(defun vc-retrieve-tag (dir name)
+  "Descending recursively from DIR, retrieve the tag called NAME.
 If NAME is empty, it refers to the latest revisions.
 If locking is used for the files in DIR, then there must not be any
 locked files at or below DIR (but if NAME is empty, locked files are
 allowed and simply skipped)."
   (interactive
    (list (read-file-name "Directory: " default-directory default-directory t)
-         (read-string "Snapshot name to retrieve (default latest revisions): ")))
+         (read-string "Tag name to retrieve (default latest revisions): ")))
   (let ((update (yes-or-no-p "Update any affected buffers? "))
         (msg (if (or (not name) (string= name ""))
                  (format "Updating %s... " (abbreviate-file-name dir))
-               (format "Retrieving snapshot into %s... "
+               (format "Retrieving tag into %s... "
                        (abbreviate-file-name dir)))))
     (message "%s" msg)
     (vc-call-backend (vc-responsible-backend dir)
-                     'retrieve-snapshot dir name update)
+                     'retrieve-tag dir name update)
     (message "%s" (concat msg "done"))))
 
 ;; Miscellaneous other entry points
@@ -2693,18 +2686,7 @@ to provide the `find-revision' operation instead."
   "Let BACKEND receive FILE from another version control system."
   (vc-call-backend backend 'register file rev ""))
 
-(defun vc-default-create-snapshot (backend dir name branchp)
-  (when branchp
-    (error "VC backend %s does not support module branches" backend))
-  (let ((result (vc-snapshot-precondition dir)))
-    (if (stringp result)
-        (error "File %s is not up-to-date" result)
-      (vc-file-tree-walk
-       dir
-       (lambda (f)
-         (vc-call-backend backend 'assign-name f name))))))
-
-(defun vc-default-retrieve-snapshot (backend dir name update)
+(defun vc-default-retrieve-tag (backend dir name update)
   (if (string= name "")
       (progn
         (vc-file-tree-walk
@@ -2714,7 +2696,7 @@ to provide the `find-revision' operation instead."
                  (vc-error-occurred
                   (vc-call-backend backend 'checkout f nil "")
                   (when update (vc-resynch-buffer f t t)))))))
-    (let ((result (vc-snapshot-precondition dir)))
+    (let ((result (vc-tag-precondition dir)))
       (if (stringp result)
           (error "File %s is locked" result)
         (setq update (and (eq result 'visited) update))
@@ -3290,7 +3272,7 @@ Invoke FUNC f ARGS on each VC-managed file f underneath it."
 ;; The performance problem, it turns out, simplifies in practice to the
 ;; problem of making vc-state fast.  The two other functions that call
 ;; prs/rlog will not be so commonly used that the slowdown is a problem; one
-;; makes snapshots, the other deletes the calling user's last change in the
+;; makes tags, the other deletes the calling user's last change in the
 ;; master.
 ;;
 ;; The race condition implies that we have to either (a) lock the master