[RFC] Workingstyle of different VCS systems

[Matthew Woehlke]

Andreas Pakulat wrote:
> before I propose an update on the VCS interface I'd like to get people's
> experience with VCS systems. I have myself good experience with CVS and
> SVN but those two are pretty similar. I also used ClearCase about 3
> years ago but don't recall the exact details.

I'm currently working with svn (yay!), but I have some experience with 
perforce. Since you didn't list that, I'll offer a quick comparison, but 
mostly it's a lot like svn (but definitely less like cvs).

> So currently we're aiming for something like this:
> 
> add - adds a resource to the VCS
> remove - removes a resource from the VCS

Yes and yes.

> checkout - fetch "something" from the VCS into a local dir

Well, perforce is a bit odd in that you have the concept of "clients", 
so to 'check out' you would create a client view mapped to a particular 
location on the local filesystem, set P4CLIENT, and then do a 'p4 sync' 
(a.k.a. update). So implementing this would involve creating a client 
specification.

> import - import a local dir into the VCS

If that is something like "add recursively", I'm not sure if the p4 
client supports it directly but it can certainly be emulated (e.g. with 
'find | xargs'), so it's still a good one to have.

> state - get the state of a local file, currently possible state flags
> 	are:
> 	Added, Uptodate, Modified, Conflict (between VCS-version and
> 	local version), Sticky (some CVS thing, no idea what it means),
> 	NeedsPatch (what does that mean?), NeedsCheckout, Directory,
> 	Deleted, Replaced

Not all states might apply, but p4 has something similar.

> commit - let the VCS transfer local changes into the VCS
> update - fetch latest changes from VCS into local dir

Yes and yes.

> log - Show a complete history for a given local resource or VCS resource

p4v (the official GUI client) does it somehow although I'm not sure 
which client commands are used. But some form of this is definitely 
applicable.

> diff - show a difference between local file and latest VCS version, or 2
>        VCS versions

Yes.

> annotate - ==svn-blame, AFAIK, i.e. show which line of a file was
>            modified by whom in which version

Hmm... newer versions of p4d are supposed to support it, unfortunately 
the server we have is too old, so I can't be authoritative here. :-(

> repositoryVersion - gives the latest version in the repository

Yes, almost the same as svn in this regard (both work on 
integer-numbered changelists). Note that perforce is a little odd in 
that you can create private changelists, which mainly means visible 
changelists are not numbered sequentially (i.e. there may be gaps).

> localVersion - gives the version of the local file

Yes. File revisions are sequential and unrelated to the changelist 
number (also, copies/branches reset the version number).

> merge - merges differences between 2 sources into the local file

p4v provides this but I am not sure that the command line client does, 
this may need to be provided externally.

> addignores - set information which files should be ignored by the VCS

Not supported. p4 ignores everything until told otherwise.

> revert - reverts local changes

Yes.

> cleanup - fix inconsistencies with the local checkout

Hmm... since I have never used anything like this, I can't tell you. 
What would this do?

> copy - copy a file with VCS methods (history is kept)

Yes.

> move - move/rename a file with VCS methods (history is kept)

This has to be done as a copy and a delete (which is how most VCS's do 
it anyway AFAIK, p4 just doesn't provide a single command to do it, so 
the plug-in would have to provide this).

> info - Show some info of the local checkout

'p4 info' gives user name, generic client info (client name, host, 
root), $PWD, $HOST (as IP address), and some information about the 
server. 'p4 files' is probably a closer equivalent to 'svn info', but 
because a client is a /mapping/ of files from repo to workspace, one 
local directory can have files from wildly different locations in the 
repository.

> mkdir - create a new directory in the local checkout and add it to the
>         VCS

AFAIK no. I don't believe there is any way to make a directory in the 
repo. New directories are created when you add a file in that directory. 
Directories are not versioned (they have no metadata and cannot exist in 
the repo without contents). IMO there should not be a 'mkdir' in the 
abstract interface, 'add' should handle it when applicable.

> resolve - mark a conflicted file as resolved

Yes, at least I think so (like I said, I don't know exactly how 
merging/resolving works because I've never tried to do it via command 
line, but p4v does it somehow.)

> lock/unlock - lock a file or VCS resource

Yes, supposedly, but I have never used these.

> special - this should be available so clients may execute special
>           actions for a specific VCS system
> 
> Do other VCS systems need other actions? Is there stuff that cannot be
> mapped to other VCS systems?

Perforce has a good bit of stuff that needs to be added in addition to 
the generic list. For instance with p4 you manage changelists, you have 
a 'default' one but you can also move files to other changelists that 
can have their descriptions set in advance. This makes it easy to work 
on multiple change sets because you don't have to tell the VCS what 
files you do or do not want to check in so often. Also it is an 'edit' 
based system, i.e. you have to 'open for edit' files that you want to 
change.

svn has propedit and friends. In p4, files have a couple of flags like 
'executable', 'keyword substitution', 'binary', etc, but that is pretty 
much it.

Maybe you should add an interface for all "common" actions (like 
property editing) but allow VCS plugins to specify which ones they 
support, and hide the others. In that case I would add to the list 
property editing and opening a file for edit.

What about support for tagging, do you think KDevelop needs to provide 
interfaces for that? (I would say "no", it's an administrative action, 
and I think those are probably better done at the command line or by a 
dedicated front-end. For KDevelop I would say focus on what you do with 
files as part of the development process.)

Overall I do think having a sort of 'standard interface' is a good idea, 
I would definitely plan to share anything we can between cvs/svn/p4 and 
maybe others (like they can have a shared diff viewer, shared 
interactive merge tool, etc). Also, p4v has a history tree that shows 
branches, integrations, etc. I think svn has the same concepts, so this 
might be a cool shared widget. However I am also thinking that it would 
be ideal to put all of this in a lib in a way that would allow it all to 
be used by other applications, for example a stand-alone dedicated vcs 
application that would use the same back-ends would rock. Obviously I 
assume all the diff/merge UI stuff will be in libraries so that you 
still have the stand-alone Kompare. There should however be an interface 
for that to allow displaying the vcs path instead of a temporary file 
name when diffing within the repo (or local vs. the repo).

BTW: you can download the p4 clients including p4v for free and I think 
a two-user p4d is also free, i.e. you could play around with it a little 
to see what it offers.

-- 
Matthew
<insert bad pun... on second thought, better not>