From acae1834c619ad1a0c8db8b6421291070087a004 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 12 Dec 2015 11:17:25 +0200
Subject: [PATCH] Document 'vc-refresh-state'

* doc/emacs/maintaining.texi (Version Control): Document
'vc-refresh-state'.

* lisp/vc/vc-hooks.el (vc-refresh-state): Doc fix.
---
 doc/emacs/maintaining.texi | 11 +++++++++++
 etc/NEWS                   |  8 ++++++--
 lisp/vc/vc-hooks.el        |  6 +++++-
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index f1a59f84351..359b50321c7 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -47,6 +47,17 @@ variable @code{vc-handled-backends} to @code{nil}
 (@pxref{Customizing VC}).
 @end ifnottex
 
+@findex vc-refresh-state
+@findex vc-state-refresh
+  To update the VC state information for the file visited in the
+current buffer, use the command @code{vc-refresh-state}.  This command
+is useful when you perform version control commands outside Emacs
+(e.g., from the shell prompt), or if you put the buffer's file under a
+different version control system, or remove it from version control
+entirely.  A companion command @code{vc-state-refresh} does the same,
+but does not consider switching the version control system or removal
+from VC.
+
 @menu
 * Introduction to VC::  How version control works in general.
 * VC Mode Line::        How the mode line shows version control status.
diff --git a/etc/NEWS b/etc/NEWS
index c6b3374ded8..01447cde163 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -321,8 +321,6 @@ the ordering of object keys by default.
 `json-pretty-print-buffer-ordered' pretty prints JSON objects with
 object keys sorted alphabetically.
 
-** You can recompute the VC state of a file buffer with `M-x vc-refresh-state'
-
 ** Prog mode has some support for multi-mode indentation.
 See `prog-indentation-context' and `prog-widen'.
 
@@ -733,6 +731,12 @@ Implemented for Bzr, Git, Hg.  As part of this change, the pre-existing
 
 *** The new command vc-region-history shows the log+diff of the active region.
 
++++
+*** You can refresh the VC state of a file buffer with `M-x vc-refresh-state'.
+This command is useful when you perform version control commands
+outside Emacs (e.g., from the shell prompt), or if you switch the VC
+back-end for the buffer's file, or remove it from version control.
+
 *** New option `vc-annotate-background-mode' controls whether
 the color range from `vc-annotate-color-map' is applied to the
 background or to the foreground.
diff --git a/lisp/vc/vc-hooks.el b/lisp/vc/vc-hooks.el
index dbe09d247b1..93d2dc0ee89 100644
--- a/lisp/vc/vc-hooks.el
+++ b/lisp/vc/vc-hooks.el
@@ -791,7 +791,11 @@ current, and kill the buffer that visits the link."
   nil)
 
 (defun vc-refresh-state ()
-  "Activate or deactivate VC mode as appropriate."
+  "Refresh the VC state of the current buffer's file.
+
+This command is more thorough than `vc-state-refresh', in that it
+also supports switching a back-end or removing the file from VC.
+In the latter case, VC mode is deactivated for this buffer."
   (interactive)
   ;; Recompute whether file is version controlled,
   ;; if user has killed the buffer and revisited.
-- 
2.39.2