[RFC] Workingstyle of different VCS systems

[Kuba Ober]

On Thursday 05 April 2007, Andreas Pakulat wrote:
> Hi,
>
> 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.
>
> So currently we're aiming for something like this:
>

In aegis, everything is done in a change, so the notion of a change always is 
there in a background. Everything that happens is manipulation of a change. A 
change should be thought of a working directory in your home directory.

> add - adds a resource to the VCS
OK, aegis -new_file

> remove - removes a resource from the VCS
OK, aegis -remove

> checkout - fetch "something" from the VCS into a local dir
OK, aegis -copy (make the file editable)

> import - import a local dir into the VCS
Has to be done by hand, basically doing aegis -new_file on each file in the 
dir

> 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
Aegis has only two possible states: a file may need to be merged with upstream 
before integration, or not. Nothing else makes any sense.

> commit - let the VCS transfer local changes into the VCS
In aegis, this is a multistep process, and ends with the change not existing 
anymore. This has to be taken care into account.

> update - fetch latest changes from VCS into local dir
OK, aegis -merge in the nutshell, but needs some logic to make sure that only 
enough of stuff got merged (i.e. you may want to merge with only the most 
enclosing branch, not with everything down to the project baseline).

> log - Show a complete history for a given local resource or VCS resource
Makes little sense. What's a resource??

> diff - show a difference between local file and latest VCS version, or 2
>        VCS versions
Makes sense, but there needs to be a way of choosing which "latest VCS 
version" do we talk about. There can be multiple branches of parallel 
development!

> annotate - ==svn-blame, AFAIK, i.e. show which line of a file was
>            modified by whom in which version
This is file difference tool specific, i.e. aegis itself is diff tool agnostic 
and by itself doesn't know much about diff tools. This would need to be made 
pluggable per diff tool used, i.e. diff-style, fcomp-style, etc.

> repositoryVersion - gives the latest version in the repository
In aegis, this needs to let you choose what do you consider as "latest 
version". The most recent version in the timeline may *not* be what you 
want - it may likely come from a parallel branch of development, and be 
completely unapplicable to whatever you're doing.

> localVersion - gives the version of the local file
East: that's just the file in the change you're working on.

> merge - merges differences between 2 sources into the local file
How is that different from update??

> addignores - set information which files should be ignored by the VCS
No such thing. In aegis, you have to add files explicitly into each change, 
those would be the project files. Everything else is handled automagically.

> revert - reverts local changes
OK, aegis -remove - simply delete the file from a change.

> cleanup - fix inconsistencies with the local checkout
OK, aegis -cleanup, this doesn't fix any inconsistencies, just removes files 
generated by the build system and only leaves the source files around.

> copy - copy a file with VCS methods (history is kept)
IIRC, aegis doesn't support this.

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

> info - Show some info of the local checkout
OK, aegis -list change_details

> mkdir - create a new directory in the local checkout and add it to the
>         VCS
Aegis handles it automatically and has no notion of empty directories, so it's 
a no-op.

> resolve - mark a conflicted file as resolved
No-op, it's automatic. Merge conflicts get marked up by the diff tool in such 
a way as to break almost any compilation out there, so once it compiles it 
means you've paid attention :)

> lock/unlock - lock a file or VCS resource
No-op, what would that be?

> special - this should be available so clients may execute special
>           actions for a specific VCS system
OK.

Cheers, Kuba