Node:Checking the state, Next:Remote repositories, Previous:Identifying backends, Up:Version-control support
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 - when running under GNU Emacs - the function
vc-state of the VC-package1 to check the state for the backends CVS, RCS, SCCS and
Subversion. 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 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 GNU Emacs' VC-package offers two different ways to get the VC-state of a file:
vc-recompute-state which always performs a
command "cvs status" 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 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 state.
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.
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 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.
The VC-package of Emacs offers a standardised and uniform interface for several backends; per default CVS, RCS, SCCS and Subversion are supported by the VC-package.