Function: vc-symbolic-working-revision

vc-symbolic-working-revision is a byte-compiled function defined in vc-hooks.el.gz.

Signature

(vc-symbolic-working-revision FILE &optional BACKEND)

Documentation

Return BACKEND's symbolic name for FILE's working revision.

If FILE names an existing directory, the BACKEND argument is mandatory. If FILE is not registered according to cached information or names an existing directory and BACKEND is nil, return nil. If BACKEND does not have a symbolic name for the working revision or Emacs doesn't know what it is, call vc-working-revision instead.

Prefer this function to vc-working-revision whenever a symbolic name will do, for it avoids a call out to the underlying VCS.

Source Code

;; Defined in /usr/src/emacs/lisp/vc/vc-hooks.el.gz
(defun vc-symbolic-working-revision (file &optional backend)
  "Return BACKEND's symbolic name for FILE's working revision.
If FILE names an existing directory, the BACKEND argument is mandatory.
If FILE is not registered according to cached information or names an
existing directory and BACKEND is nil, return nil.
If BACKEND does not have a symbolic name for the working revision or
Emacs doesn't know what it is, call `vc-working-revision' instead.

Prefer this function to `vc-working-revision' whenever a symbolic name
will do, for it avoids a call out to the underlying VCS."
  ;; Returning nil if the file is unregistered (which is why we call
  ;; `vc-backend' even if BACKEND is non-nil here) makes us closer to a
  ;; drop-in replacement for `vc-working-revision'.  Don't actually
  ;; query the VCS because the point of this function is to avoid such
  ;; queries.  Code that purely wants to map BACKEND to a symbolic name
  ;; can call the backend API function directly.
  ;; (If we don't check whether FILE is registered, then whether this
  ;; function is sensitive to FILE being registered depends on whether
  ;; BACKEND implements `working-revision-symbol' (because we would be
  ;; sensitive to whether FILE is registered if and only if we defer to
  ;; `vc-working-revision'), which would be a strange interdependence.)
  ;;
  ;; Similarly, for consistency with `vc-working-revision',
  ;; return nil for directories unless BACKEND is specified
  ;; (`vc-backend' always returns nil for directories).
  (let (cached-backend)
    (and (or (and (file-directory-p file) backend)
             (setq cached-backend (vc-backend file)))
         (let* ((backend (or backend cached-backend))
                (fn (vc-find-backend-function backend
                                              'working-revision-symbol)))
           (if fn (funcall fn) (vc-working-revision file backend))))))