Development and Project Support

(Note that Repositories^? are a separate topic.)

Projects

Version Control

Current leading distributed SCM contenders: Git, Mercurial. SVK is still a nice front end for Subversion, but I'm not using it any more in practice. Bzr has since been added into the mix, not because of capability but because a couple of projects I'm interested in use it, and the FSF appears to be endorsing it.

As of March 2008, Mercurial is still the one deployed for automated backups on the FINI machines, as it was the only one easily built and usable on the old wakko, and because it keeps running without any particular effort. I also deployed Git, and am using it at home. SVK is still in use to mirror SpamAssassin (until it breaks or I get around to replacing it).

Bzr

Bazaar, itself a re-design of Arch, re-written into python and with a faster back end. Supported (somewhat) by Canonical, and reportedly now a "GNU Project". Distributed. Slower than Git or Mercurial and has a smaller following than either. (Still more than SVK, though! And the supporters tend to be more rabid than Mercurial's.)

As yet, I'm not using it for anything or tracking any project using it. The FSF has come out in its favor, and Emacs is being officially supported in it now, though at the time of writing they had yet to officially phase out the CVS repo. (There was also a rogue site mirroring the Emacs CVS repo into Git. Better. )

CVS

Still the most widely used SCM system. For FINI, suggest it be viewed as legacy only. Just import or convert from it into other SCM's as needed. Subversion covers the same territory better. Non-distributed.

If you must use CVS, there's a "secure" version available from the OpenBSD folks.

Utilities exist to pull or convert from it to all four candidate distributed SCM's. At present, it seems easiest to convert to Subversion or Git. (And until recently, the mercurial project recommended converting to one of these two first before importing.)

Darcs

Written in Haskell. Based on a "theory of patches".

Pro: very good at handling patch collections and merger. Good external SCM translation system exists (tailor, usable by other SCM's). Enthusiastic community.

Con: much less speedy with a few pathological slowdowns, increasingly so as project size scales up. Slightly less flexible in branching than the other distributed SCM's. Doesn't extend or call well with declarative languages.

I plan to steer clear of it for now.

Git

• Written mostly C with some shell. gitweb uses perl

Git is the official SCM of the linux kernel. It is also used by OLPC, X.org, Wine, etc. While not final, it appears that the perl project is changing to git.

Pro:

• very very fast, very scalable, distributed design
• very widely used, very active community
• reasonably secure remote operation, by several channels
• cryptographic signatures are available
• toolkit design, with the lower level tools available but not required
  • easy (well, comparatively) to interface with
• interfaces well with svn, and conversion possible from most vcs'es

Con:

• learning curve and lack of documentation (both of which situations have improved greatly, but...)
• need for occasionally repacking repository. (But added automatic repack at 1.5.4).
• git is still evolving, if more slowly.
  • The native "user-friendly" user interface (aka "git porcelain") is a recent addition
    • And under active development.
    • Common operations are stable but may evolve easier alternative phrasing.
    • Cogito, the older user-friendly front end, is now deprecated.
      • But if you have to face an ancient git (why?), learning cogito is probably easier.
  • Git documentation is thus distressingly version-specific. Older docs use superceded or un-necessarily complex methods, very recent docs may show command variants that are not yet available in your linux distro. Very old docs show frighteningly alien methodologies... which (mostly) continue to work, but still...
  • git version packaging by linux distros is confusing, especially on debian/ubuntu

Packages/extensions (gitwiki has a more extensive list:

• git itself (git-core), now includes an "easy" line mode user interface.
  • git-docs, git-gui, gitk and gitweb are shipped with core but may be split when packaged
• cogito, a deprecated easy line mode user interface (don't bother installing)
• Easy Git (eg) is a recent (and preliminary) git front end in perl
  • not part of the git project, but a suggestion by an outside reviewer
  • not known to be used in production as of March 23, author says it's buggy
• git-cvs imports CVS repositories
• git-svn imports from subversion repositories
• StGIT ("stacked git") provides quilt-like management of patches in a subsystem
• guilt is a competing quilt-like patch management system, newer and less common.
• Git-GUI is a simple graphical interface. In TCL/TK (sigh).
• kgit is a "small but functional" gui front end in qt (kde-ish)
• gitk is a repository visualization tool
• qgit is another repository history tool with more features, in qt (kde-ish)
• giggle, ditto but using gtk+ (gnomish)
• gitview, ditto but using gtk and python.
• gitweb is a web interface for repositories
• gitsplit, python tool to split out subproject git repositories
• gitfs, fuse filesystem access into a git repository
• meld (gnome merge tool) is now supported post-git-1.5.1, via git-mergetool
• kdiff3 and xxdiff (kde merge tools) are now supported via git-mergetool
• tkdiff is now supported via git-mergetool
• metastore, preserve file metadata in a git repository [unclear how, look this one up]
• Git perl bindings (perl-Git under fedora/centos)

Integration:

• emacs has git.el and vc-git.el, emerge is supported via git-mergetool.
  • Recently supported by the emacs DVC project, but it is not in emacs yet.
• eclipse has an early plugin, said usable but with horrible warnings
• (Not yet: bugzilla and TWiki are on the official wishlist)

Installation notes:

• Make sure you're using version 1.5 at minimum.
  • External merge tools (git-mergetool) require 1.5.1 or better
  • 1.5.2 brought worthwhile syntax improvements. 1.5.4 even more.
  • At time of writing (20080321) stable version is 1.5.4.4
• You may also want stgit (and/or guilt) for patch manipulation, and an external merge tool.
• If on centos, enable rpmforge and yum install git git-gui
  • stgit does not seem to be available from rpmforge
• If on fedora using extras: yum install git stgit
  • yum install git pulls in git-core git-svn git-cvs git-arch git-email gitk git-gui and perl-Git
    • THIS WILL CHANGE. In Fedora 9, you will have to pull them in individually.
  • stgit, giggle, qgit and the git trac plugin (at least) are also available from extras
  • kdiff3 and meld merge tools are also available
• If on ubuntu or debian
  • Enable backports (feisty or below) or you're stuck with an unusably ancient version.
  • apt-get install git-core git-doc git-svn git-cvs git-gui gitk stgit
  • gitweb, qgit, and (?? quite a lot ??) are also available
  • kdiff3 and meld merge tools (and others) are available.
    • warning: meld tries to pull in most of gnome and its media players on ubuntu
  • Before debian etch or ubuntu gutsy, you have to manually invoke alternatives for git
    • By default, their git refers to gnu interactive tools rather than git-core
    • ubuntu feisty at least prompts you to do this when you install the backport git-core

Tutorials, howto's and cheat sheets:

• see /usr/share/doc/git-core (and/or git-doc) for release-specific documentation
• GIT Quick Start
• Git User Manual
• Everyday GIT with 20 Commands or so
• Git - SVN Crash Course
• "GIT for mortals" ref & cheat sheet
• Git FAQ
• Git for Computer Scientists, technical repository overview
• Introduction to git-svn for Subversion/SVK users and deserters

More of the same:

• Put /etc under Revision Control
• etc snapshots with git
• sourcemage git cheat sheet
• one user's git cheat sheet
• using Git to maintain patches against Wine
• Learning to Love Git (older)

Extensions:

• An introduction to git-svn for Subversion/SVK users and deserters
• StGIT Tutorial
• git subproject (submodule) support

Links:

• Git wiki is a good place to check
• gitwiki compilation of git links
• Getting Started with Git (LWN)
• IsiSetup is a config file manager using Git as a back end.

Videos:

• Linus' talk on git

Other uses:

• "It is believed" that the unofficial extension package that lets TWiki 4.0 (obs) work with mercurial is modifiable to allow it to work with git. Not directly useful. There is a very nice tutorial on converting the CVS-like RCS logs produced by twiki into SVN or Git format during TWiki-to-ikiWiki conversion. (Think I saw an article by someone who did adapt TWiki to use Git, but can't find it right now.)

Mercurial, aka hg

Written in python. Official VCS of Mozilla, OpenSolaris, and Xen.

Pro:

• fast, small, uncluttered, with few pre-reqs,
• Well documented, large community.
• Runs well under Microsoft Windows. (Which Git does not.)
• Repository conversion utilities are available for CVS, Subversion, Darcs, Git, etc.
• It has a patch management extension (MQ) included.
• Plugins are available for eclipse, emacs, vim and other editors and IDEs.

Con:

• Proliferation of repositories
  • Not required, but the most described workflow keeps one repo per branch
• Versions below 0.9.4 do not handle symlinks.
  • Centos 4 distributed 0.9.3, but fortunately rpmforge provides 0.94.
  • Ubuntu feisty provided 0.9.3, with no upgrade version in backports

Notes:

• The 1.0 conversion on the RPMForge repo in early April 2008 resulted in thousands of warning messages every night as it reported "this file is still here" for everything in each repository. It turned out to be cosmetic, the side effect of a command syntax change: there is now an addremove command, that subsumes the previously recommended remove --after when misusing mercurial to snapshot directory content. With 1.0, remove was changed to work the same way but always issue a warning. Caught my attention, alright! This experience does partially shoot down the "mercurial is better than git because its user interface is more stable" argument.

Documentation:

• The Mercurial quick start, wiki, book, tutorial
• Quick reference cards
• Mercurial Centralized HOWTO
• Setting up a Mercurial repository from SVN for dummies

Videos:

• Introduction to Mercurial (google talk)

Other uses:

• There is an unofficial, experimental contributed package to change from RCS to mercurial for TWiki 4.0 version control. It is not marked as tested against 4.2, and the author has abandoned the package in favor of RcsSyncAddOn, which was tested against 4.1 and is also not known to work with 4.2, and which is mostly a way to synch twikis.

RCS

RCS is still in play thanks to TWiki. (It is rumored that a future version will use Subversion directly.) It's also useful for simple locked single-file revision tracking.

Cheat-sheet example of off-wiki rollback for TWiki:

• cd /www/sys/twiki/data/Main
• sudo -u apache rlog TermsandConditions4.txt
• # identify the last good version, here 1.2
• sudo mv TermsandConditions4.txt TermsandConditions4.txt.OLD; sudo -u apache co -r1.2 TermsandConditions4.txt
• sudo -u apache vi TermsandConditions4.txt # add the protection stanza
• sudo -u apache ci -l -mnone -wCynthiaManuel TermsandConditions4.txt
• sudo -u apache rlog TermsandConditions4.txt # make sure it "took"
• ls -lZ TermsandConditions4.txt* # check the permissions (leave off Z if no selinux)

The -r is revision, -l is "leave file", -m is comment, -w owner.

Subversion (aka SVN)

Written in C. Official VCS of lots of projects. "CVS done right."

Pro: very large mindshare, ubiquitous. Lots of extensions and front ends and translators. Well documented.

Con: non-distributed, central management with no disconnected operation. Branching awkward (?) and merging painful. Server setup non-trivial, and is additional admin overhead.

• Book

At its best when used through SVK. Good support from git, and mercurial recently added its own rather than simply recommending conversion to git first.

SVK

Written in perl. Distributed operation. Still a contender, but only just.

Pro: (Optionally) uses subversion as transparent back end, but it's much more than that. Nice merge features and faster operation than native svn, handles patching and tracking well. Lightweight checkout. (Repository info doesn't clutter up the work area.)

Con: Lack of good (or even bad) documentation. Slow (and much slower than bzr, git or hg). Small user community, tiny developer community. Learning curve. Lots of pre-requisite packages. (And one of them required for direct CVS access is not in Fedora repos.) Rumors and confirmed rumors of bugs.

• The SVK wiki

book (incomplete) tutorials

• Articles to read: perlmonks

r/o-mirror wordpress distributed

From my view, SVK is no longer a front runner, if still a nice subversion front end.

• Support/install difficulties:
  • Official 2.02 dependencies are unavailable in 5.8-based perl distros.
  • It is only available pre-built in a very old (1.08!) version under ubuntu feisty.
  • Not available pre-built at all on Centos! (May build it myself eventually.)
  • OTOH, 2.02 is now available for Fedora 6 and above.
• It has less support for converting from/tracking legacy repositories than Git or Mercurial.
  • And even CVS support isn't pre-built under Fedora.
  • OTOH, it is unmatched for working with SVN databases. So if you only want to convert rather than pull from a legacy format, and if there's a SVN converter for that format, there's a workaround.
  • OTOH, as of August 29th, there are perl packages on CPAN that potentially could allow SVK2 to access git and mercurial archives.
• There are persistant rumors that SVK can corrupt its databases.
  • True. Have had this happen when I tried moving apparent location of a branch within the repository.
  • To be fair, I was using advanced tools by rote without requisite knowledge. And have no idea how to do the same thing under the other two. And might never need to. Repository control differs dramatically.
• While it doesn't absolutely require a running SVN system to back it up, it still stores its data in SVN format and SVN is a prerequisite for normal remote operation. (There is an alternate mode using ssh.) The other two SCMs can operate in "central repo mode" with less hassle.
• I still find SVK somewhat more intuitive than Mercurial or Git, much more so than Subversion.
  • But that is slowly changing as I get used to the git/hg workflow.
• Still using it to track SpamAssassin, etc.
  • But have set up a parallel project with Git.
  • SVK feels a lot slower after using Git and Mercurial.
  • As a result, I haven't been using SVK at all recently.

Others of Interest

• Monotone
• Quilt

Tools and Programs using source control

• EtcKeeper (now git, hg or bzr)
  • See also etc snapshots with git
• ikiWiki can use a SCM for management of its uncompiled files. svn, git, hg and bzr are supported. ikiWiki itself is developed in Git, and it seems to be the most popular (although their recommended setup is not obvious...) See also laptop wiki with git .
  • It is possible (with obvious limitations) to convert from TWiki to iki, including migration of page history. The hurd project recently converted from TWiki to an ikiWiki with git source control, and published how they did it.

Comparison

• happenings in vcs world (summary: hg easier, git more capable but not recommended yet)
• Theodore Tso is moving from mercurial to git and, while agreeing that git docs need work, disagrees on not recommending it.
• why users are more error prone with git (useful insight into workflow)
• "Should I look at revision control software other than Subversion"

(The author chose mercurial. In comments, darcs was slightly more popular. The SVK contingent was sadly outnumbered.)

• git vs. hg blog article (favors git)
• Repository Formats Matter (favors git)
• slashdot on git (don't bother)

Issue tracking

Bugzilla

Written in perl. Bug tracking.

Trac

Written in python. Integrated issue tracking and wiki with Subversion back end.

-- JohnLundin - 05 Apr 2008