DollarFreeBSD [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== Description =====
CVS includes expansion of $%%FreeBSD%%$ to revision number of the file's most recent change on checkout.  This makes it possible to:

  * Easily see which revision a source file is at
  * Easily see whether a source file is affected by a security issue ("Revisions of foo.c after 1.12 do not have this problem")
  * Easily see which revisions of source files a binary is built from

The alternative VCS does not need to support $%%FreeBSD%%$ directly.  However, it must provide a mechanism to allow developers and end users to carry out those three tasks.

The use of $%%FreeBSD%%$, rather than the more common $Id$ (in CVS) is so that if we import files from other projects that use $Id$, we don't end up clobbering their version number with the version number in our repo.

===== Current Implementation =====

===== SVN Implementation =====

This is [[http://subversion.tigris.org/issues/show_bug.cgi?id=890|issue#890]] in the Subversion issue tracker.  The bulk of the code to implement this is already in Subversion -- what's missing is a per-repository configuration mechanism that can enable it.  Without it, any client that accessed the repository would need to be patched to support $%%FreeBSD%%$, and any other custom keywords.

===== Hg Implementation =====
Hg by default does no keyword expansion at all.  There are practical reasons not to do this (including the fact that it does complicates the job of the VCS) but it is seen as %%FreeBSD%% developers as a useful feature.  Therefore, someone has written an Hg extension to do expansion of certain keywords.

This allow for the hash of the changeset that touched a file last to be inserted in the file like $Id$.

Like git, hg does have some commands to give information about files and revisions: ''%%hg tip%%'' gives you the revision your repository is at, ''%%hg log%%'' gives you the entire history of the repository or files you are looking at.

===== Git Implementation =====
This could be done within whatever CVS importer tool is used for existing CVS revisions, as that tool is writing out the blobs and has access to the CVS revision numbers at the same time.  This isn't done in ''%%parsecvs%%'' yet, but would be easy.  However, this revision numbering wouldn't be maintained for new commits to git (since it's distributed, and there's no way to make sensical monotonically-increasing version numbers in a distributed system).

For discussing revisions in debugging, ''%%git show%%'' shows what sha1 is at the top of your current branch, ''%%git-rev-list%%'' shows what sha1s are in the history of your branch, and comparing the position a user's latest sha1 with the sha1 of a fix you did in the ''%%git-rev-list%%'' tells you if a user has a given fix in their tree.

There has been recent work to add checkout hooks to git which would make it easy to have keyword expansion on checkout which could then be compiled into a file and identified with ident(1) or what(1).

Recent commits to the git repository have added support for receive and checkout filters which have added support for imploding an exploding an $ident$ keyword. So git can now support this.

===== Monotone Implementation =====
**Partially Supported**
(also see [[http://venge.net/monotone/wiki/FeatureEmbeddedIDs|monotone:FeatureEmbeddedIDs]])

Monotone does not directly support automatic expansion of version strings or other keywords inside file content.  Because the SHA-1 hashes of file content are crucial, and because these kinds of flags have proved difficult and confusing in some other systems, implementation of this feature has been avoided up to now -- mostly for lack of a compelling use case.  It is certainly possible to add.

Some of the cases where this kind of feature is used in other systems are better addressed by other mechanisms in monotone; the first requirement (see which revision a source file is at) is actually very easy: the file's SHA-1 hash **is** the version itself, so having the id in the file itself is not needed to identify unchanged files.  This would not address the requirement that binary files contain the revision, though.

It is possible to approximate this feature, if needed, using hooks. A custom attr could be attached to files that need such expansion, and an attr-hook defined in lua to perform the substitution.  Another possibility may be an implementation similar to that used to handle platform-specific newline formats, generalising that to other kinds of filters. In any such implementation, it would be vital to ensure that the content of the file seen for commit has been sanitised to contain only the bare keyword in a 'canonical' form that is stable between revisions.