That file contains the documentation to build support for a different dvc,
using the dvc layer:

Conventions used in the document:
* <dvc> is used as placeholder for the dvc backend to implement

--------------------------------------------------------------------------------
* Base functions that are required for every supported dvc system
* That functions should be located in the <dvc>-dvc.el file
--------------------------------------------------------------------------------

When no function is provided, dvc-dvc-<postfix> is used instead.

- <dvc>-dvc-tree-root
   (defun <dvc>-dvc-tree-root (&optional location no-error)
     "Return the tree root for LOCATION, nil if not in a local tree.

   If NO-ERROR is non-nil, don't raise an error if LOCATION is not a
   <dvc> managed tree (but return nil)."

- <dvc>-dvc-log-edit-done
   (defun <dvc>-dvc-log-edit-done ()
     "Finish a commit for <dvc>."

- <dvc>-dvc-diff
   (defun <dvc>-dvc-diff ()
     "Shows the changes in the current <dvc> tree."

- <dvc>-dvc-log
   (defun <dvc>-dvc-log ()
     "Shows the changelog in the current <dvc> tree."

- <dvc>-dvc-command-version
   (defun <dvc>-dvc-command-version ()
     "Returns and/or shows the version identity string of backend command."

- <dvc>-dvc-file-has-conflict-p
   (defun <dvc>-dvc-file-has-conflict-p (filename)
     "Return non-nil if FILENAME is marked as having conflicts")

- <dvc>-dvc-resolved
   (defun <dvc>-dvc-resolved (filename)
     "Mark FILENAME as not having conflict anymore")


To handle the case of a workspace that is controlled by more than one
back-end, all dispatching interactive front-end functions dvc-foo
should have a corresponding function <dvc>-foo, that specifies which
back-end to use.

A simple way to provide <dvc>-foo is to put dvc-foo in
dvc-back-end-wrappers (in dvc-unified.el); then <dvc>-foo is
automatically generated by dvc-register-dvc. This defines
<dvc>-foo as (see dvc-register.el for the actual code):

    (defun <dvc>-foo (<args>)
        (interactive)
        (let ((dvc-temp-current-active-dvc <dvc>))
            (call-interactively 'dvc-foo)))

This means that back-ends may _not_ define a function <dvc>-foo.

Note that functions defined by dvc-define-unified-command dispatch
to <dvc>-dvc-foo. Calling <dvc>-dvc-foo is _not_ the same as
calling <dvc>-foo, since dvc-temp-current-active-dvc is not bound,
the interactive argument processing may be different, and
<dvc>-dvc-foo may not even exist (if the default dvc-dvc-foo is
sufficient).

-----------------------------------------------------------------------------
* Revision API
-----------------------------------------------------------------------------

Definition
==========

DVC deals with several RCS, with different ways to designate a
revision. We define a unified way to designate a revision in lisp,
which we call revision identifiers, or rev-id:

REVISION-ID :: (<dvc> BACK-END-ID)
  ;; <dvc> is one of 'tla, 'bzr, 'xhg, ...

BACK-END-ID :: (revision BACK-END-REVISION)
  ;; An already commited revision
  ;; The way to specify it depends on the back-end.
             | (local-tree PATH)
  ;; Uncommited revision in the local tree PATH
             | (last-revision PATH NUM)
  ;; Last commited  revision in tree PATH if NUM = 1
  ;; Last but NUM-1 revision in tree PATH if NUM > 1
             | (previous-revision BACK-END-REVISION NUM)
  ;; Nth Ancestor of BACK-END-ID.

(probably we'll need a (head REMOTE-BRANCH) too)

PATH :: string
  ;; must be a tree root directory

NUM :: number

REV-STRING :: string

For Xtla (tla and baz):

BACK-END-REVISION :: ("archive" "category" "branch" "version" "revision")
  ;; archive/category--branch--version--revision

For bzr:

BACK-END-REVISION :: (local "path" NUM)
                   | (remote "url" NUM)
                   | (tag REV-STRING)

For xhg:

TODO

For xgit:

BACK-END-REVISION :: (revision "sha1")
                   | (index)
  ;; content of the index (aka staging area).

Example
=======

(bzr (revision (local "/path/to/archive" 3)))
(baz (last-revision "/path/to/project" 1))
(baz (revision ("archive" "category" "branch" "version" "revision")))
(xgit (revision "c576304d512df18fa30b91bb3ac15478d5d4dfb1"))

Functions
=========

Based upon that, we define the functions:

dvc-revision-get-file-in-buffer: get the particular revision of a file
                                 in a buffer.

-----------------------------------------------------------------------------
* Back-end specific features Vs Unification
-----------------------------------------------------------------------------

DVC provides the user an interface for multiple revision control
system, and does it using as much back-end independant code as
possible. This has several benefits :

* For the user:
  - Similar user-interface, keybindings, ... for different back-ends.
  - Unified interface for most operations : one menu, one set of
    keybindings, and DVC detects which back-end to use automatically.

* For the developers:
  - much less code to write than individual, independant interfaces.

However, some back-end features do not fit well in the DVC common
interface. For example, git differs from other common version control
systems in several regards (the index, for example, is something
probably unique to git, and it leads to a different flow to prepare a
commit).

In this case, there's nothing wrong providing additional functions,
which might not have a dvc-* dispatching command. The user can call
them with M-x <back-end>-command RET explicitly. Additionaly, one can
extend some DVC modes with additional keybindings and menus. See
`dvc-diff-mode' and `xgit-diff-mode' for an example.

-----------------------------------------------------------------------------
* External tools
-----------------------------------------------------------------------------

* 'sh' is required for dvc-run-sync and dvc-run-async.

  In practice, that is not a problem for Unix users, but requires
  cygwin or mingw for Windows users. 'sh' is used to separate stdout
  from stderr; the Emacs function 'call-process' merges them. It may
  be possible to do this with native Windows tools, if someone wants
  to investigate.
