After ECB has identified the VC-backend of a directory it will display the VC-state (e.g. up-to-date, edited, needs-mergs etc...) with a suitable image-icon in the tree-windows of the ECB-file-browser. To get this state for a certain file ECB uses that check-state-function stored in the cache for the directory of that file (see Identifying backends).
You can add any arbitrary functions as check-state-function to
ecb-vc-supported-backends
as long as they get one
filename-argument and return a state-symbol (e.g. up-to-date
.
ECB can understand a certain set of state-values which are then
mapped to suitable image-icons which will in turn be displayed in
front of the filename in the file-browser. Because the values a
check-state-function return can differ from that state-values ECB
understands, ECB offers an option to define a appropriate
state-mapping. The name of this option is ecb-vc-state-mapping
.
See the documentation of this option to get a list of all state-value
ECB understands.
Per default ECB uses the function vc-state
of the
VC-package1 to check the state for the
backends CVS, RCS, SCCS, Subversion, Git and Monotone. So the default-value of
ecb-vc-state-mapping
contains a mapping between these values
ecb-vc-state
can return and that state-values ECB understands.
If ECB should support other VC-backends than CVS, RCS, SCCS, Monotone, Git and
Subversion (e.g. Clearcase) you should add that new backend to the VC-package
(see the initial comments of vc.el how to do this) then ECB will automatically
support that new backend. Alternatively it may be sufficient if you write your
own check-state-function for this backend and add the needed mapping to
ecb-vc-state-mapping
if necessary.
The interface of Emacs' VC-package offers two different ways to get the VC-state of a file:
VC has a function vc-recompute-state
which always performs a real
backend command (e.g. “cvs status” for CVS) to get a fresh and real state
for a file. As you can imagine this operation can be very expensive and long
lasting depending on the location of the repository. But for CVS the
CVS-backend of VC offers with the option vc-cvs-stay-local
a way to
tell Emacs to stay local even for the sake of getting a real
state2.
ECB offers ecb-vc-recompute-state
for this approach which is an alias
for vc-recompute-state
.
The function vc-state
always returns a “heuristic” state
which should be used when a fresh and real state is not necessary.
With vc-state
the option vc-cvs-stay-local
will never
take effect.
ECB offers ecb-vc-state
for this approach - see below for the
difference between vc-state
and ecb-vc-state
.
Example CVS:
VC/CVS actually does it this way (regardless if ECB is active or
not): When you visit a file, it always uses just the heuristic to get the
state (comparing file times), regardless of the setting of
vc-cvs-stay-local
. This is because the "fresh-but-slow" state is
determined by calling "cvs status" on the file, and this was deemed
unacceptably slow if done at visiting time under any conditions.
The state is updated by calling vc-recompute-state
prior to
vc-next-action
(C-x v v) which either checks a file in or out.
IF vc-cvs-stay-local
is nil, then this does in fact call "cvs
status" to get the "fresh-but-slow-state", but if
vc-cvs-stay-local
is t, then it just compares the file times
again.
But under certain conditions (e.g. if called for files not already
visited or for files their VC-state has been changed from outside
Emacs, e.g. by checking in the file via command line) vc-state
does not compute a new heuristic state but returns a cached one
(cached by the VC-package itself not by ECB) which does not reflect
the current VC-state. Example: if you have edited a file within Emacs
and then checked in from outside Emacs vc-state
returns a wrong
state until you call revert-buffer
for this file. Therefore ECB
offers the check-state-function ecb-vc-state
which does the
same as vc-state
but it clears the internal caches of the
VC-package for that file before calling vc-state
.
The bottom line for you is this: If you use ecb-vc-state
in
ecb-vc-supported-backends
to get the version control state, then you
get the same policy that VC uses and you get always a “correct” heuristic
state (as correct as possible a heuristic state can be). There should no harm
if you use ecb-vc-recompute-state
(which is an alias for
vc-recompute-state
) as a replacement function if you want to get fresh
and real state-values, but then (a) you must make sure to set
vc-cvs-stay-local
to nil, and (b) fetching the state over the network
under all conditions was deemed unacceptably slow in VC.