Checking the state - ECB - the Emacs Code Browser
Description: ECB - the Emacs Code Browser

Next: Remote repositories, Previous: Identifying backends, Up: Version-control support

#### 10.8.2 How ECB checks the VC-state of a file

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.

##### 10.8.2.1 Getting heuristic state-values or real ones for a backend

The interface of Emacs' VC-package offers two different ways to get the VC-state of a file:

- The real, fresh and expensive approach

  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 heuristic approach:

  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.

#### Footnotes

[1] The VC-package of Emacs offers a standardised and uniform interface for several backends; per default CVS, RCS, SCCS, Subversion, Git and Monotone are supported by the VC-package.

[2] For other backends you have to check the VC-manual if there is equivalent option