[darcs-users] revision identifiers

Max Battcher me at worldmaker.net
Sat Mar 29 06:15:49 UTC 2008


First of all, I think you've hit the head on the nail that Documentation 
can be a wonderful tool.  There certainly could be a lot of good work 
put into cleaning up/adding to the Darcs Wiki and the "Understanding 
Darcs" Wikibook and the Darcs Manual.  It might be a great project for 
some prospective "Summer of Code" student, even if not officially part 
of the Google+money one.

Declan Naughton wrote:
> I think the power that darcs allows in cherry-picking is wondrous, but
> don't you think it lets itself down to newcomers because it's so much
> more of a task to simply get a specific revision on which to build
> compared with Hg and git? 

If I want you to build a very specific revision that isn't tagged, I'm 
probably going to ask you to pull directly from my repository that I've 
left in that state.  One of the distributed SCM things that neither Hg 
or Git seem to push/encourage anywhere near as much as darcs is the idea 
that rather than do everything under the sun in a single working 
directory (repository), it's just as simple to copy the repository in 
whole in the state that you want it.  It's quite possible for you to 
have a number of repository copies in different states.  It isn't even 
all that inefficient because Darcs will try to hard link patch files on 
file systems that support that.

So, I might have

/repos/aproject/main
/repos/aproject/test-new-feature
/repos/aproject/integrationA
/repos/aproject/integrationB
/repos/aproject/unstable
...

If I want you to test a new feature in aproject with me, I could tell 
you the patches to pull, or I could send you a context file against my 
'main' or 'unstable' branches or I could just ask you to get 
http://repos.worldmaker.net/aproject/test-new-feature and Darcs will 
replicate that version of the repository exactly.

If for whatever reason I decide to archive 
/repos/aproject/test-new-feature, but want to keep the final state of 
that for future use, then I might convert it into a context file.

> They will need to get the tag previous to
> the revision they want, and then 'darcs pull' and run through the
> patches (unless the revision is tagged, which I guess would be most
> common, but still). This is more flexible (and extremely useful. Since
> darcs is available with this power, I'm trying to consider only this,
> and I think that's why it needs to focus on usability and
> documentation, because it's easy to just fuck darcs off and use Hg),
> but I think it's a fairly common use case to wish to reproduce a
> revision without any differences to how the repository produced it,
> and therefore revision identifiers like Hg and git use would be useful
> (even if only slightly after users become more adept) as well as
> context files.

It's a fairly common *set* of use cases.  Getting to a particular 
version of a remote repository versus getting to a particular version of 
the current repository versus communicating repository states versus 
examining recent history...  You may not notice it as much, but to my 
knowledge even Hg and Git have somewhat different notions of local and 
remote revision numbers.

Darcs doesn't store revision numbers because they'd be too confusing and 
wouldn't really make sense for most cases.  To darcs, history isn't a 
tree written in stone as it is to Hg or Git, it's a flowing river whose 
bed may shift with time and necessity.  The benefit to the "river 
approach" is that mergers are easier (in the general case), and thus 
cherry-picking is easier.  The trade-off is that there is no concrete 
way to say "here's how the repository was *exactly* at time x", because 
darcs doesn't store that information and in some ways that information 
would get in the way more than it would help.  Plus, if it stored all 
integration states ("commutations") you'd certainly end up with a lot 
more information than you actually care about...

Darcs offers a number of tools to reproduce various versions of a 
repository.  Ultimately the right one for the job depends on the use 
case in darcs.  Some of them are documented in the Wiki, maybe someone 
should take the time to rundown others as specific tutorials.

> Consider how daunting it is for a Hg user trying to grasp darcs to run
> 'darcs changes' and find absolutely no identifier to jump back to a
> mildly-old version of the repository... (something about unrecord
> frightens me, but do explain how it can/can't be used if it would
> help)

I'd probably try ``darcs annotate`` or ``darcs diff``, first.  But the 
pattern of:

darcs get repo-a repo-a-copy
cd repo-a-copy
darcs obliterate # aka darcs unpull

Is rather straight forward, too.  (To a certain extent, that's sort of 
what ``darcs diff`` does in the background, anyway.)

Hopefully this helps,

--
--Max Battcher--


More information about the darcs-users mailing list