NWRUG July 2009 - Darcs

Manchester
July 2009

darcs
An introduction to a fully-distributed
revision control system

Ashley Moran
Creative Commons Attribution-Noncommercial-Share Alike
2.0 UK: England & Wales License PatchSpace Ltd

What is darcs?

distributed
interactive
smart
patch-based, not revision/history based
written in Haskell

Presentation goals

To show how darcs makes revision control
easy, interactive, and intuitive
To show you how to think in terms of
patches, not revisions
To help you compare darcs to git (in the
narration, a video, and questions)

Presentation non-goals
To show every last feature of darcs
Even some really cool ones are omitted
To show "best practice" workﬂows
To explain the patch theory that
underpins darcs
To convince you that darcs is better than
git/hg/bzr/svn

Initialising a repository
% mkdir repo_a

% cd repo_a

repo_a % darcs init

repo_a % ls
_darcs

repo_a % darcs changes
No patches yet

Adding a ﬁle
repo_a % echo "Hello, darcs" > hi.txt

repo_a % darcs whatsnew
No changes!

repo_a % darcs whatsnew --look-for-adds
a ./hi.txt

repo_a % darcs add hi.txt

repo_a % darcs whatsnew
addfile ./hi.txt
hunk ./hi.txt 1
+Hello, darcs

Recording a patch
repo_a % darcs record
addfile ./hi.txt
Shall I record this change? (1/2)
[ynWsfvplxdaqjk], or ? for help: y
hunk ./hi.txt 1
+Hello, darcs
What is the patch name? Say hello to darcs
Do you want to add a long comment? [yn]n
Finished recording patch 'Say hello to darcs'

Listing patches
repo_a % darcs changes
Mon Jul 13 12:31:48 BST 2009
ashley.moran@patchspace.co.uk
* Say hello to darcs

darcs got my email address from the
DARCS_EMAIL environment variable

Cloning a repository
repo_a % cd ..

% darcs get repo_a repo_b

% cd repo_b

repo_b % darcs changes
Mon Jul 13 12:31:48 BST 2009 ashley.moran@patch…
Repo B is a clone of Repo A

Modifying a ﬁle
repo_b % echo "How are you?" >> hi.txt
repo_b % darcs whatsnew
hunk ./hi.txt 2
+How are you?
repo_b % darcs diff --unified
diff -rN -u old-repo_b/hi.txt new-repo_b/hi.txt
--- old-repo_b/hi.txt
2009-07-13
14:55:21.000000000 +0100
+++ new-repo_b/hi.txt
2009-07-13
14:55:21.000000000 +0100
@@ -1 +1,2 @@
Hello, darcs
+How are you?

Adding a directory
repo_b % mkdir src

repo_b % echo 'puts "Hi"' > src/hi.rb

repo_b % darcs add -r src

repo_b % darcs whatsnew --summary
M ./hi.txt +1
A ./src/
A ./src/hi.rb

Record interactively
repo_b % darcs record
hunk ./hi.txt 2
+How are you?
[ynWsfvplxdaqjk], or ? for help: n
adddir ./src
[ynWsfvplxdaqjk], or ? for help: a
What is the patch name? Added application source
Do you want to add a long comment? [yn]n
Finished recording patch 'Added application
source'

Record all
repo_b % darcs record -a -m 'More hellos'
Finished recording patch 'More hellos'

repo_b % darcs changes
* More hellos

* Added application source


Showing patch contents
repo_b % darcs annotate -p 'More'
[More hellos
ashley.moran@patchspace.co.uk**20090713145126
Ignore-this: 27105a11a78c889107399e21d7b9dea0
] hunk ./hi.txt 2
+How are you? darcs annotate has another use -
the name is not very intuitive here

This named patch contains
only one change

More patch contents
Regex example to locate the patch
repo_b % darcs annotate -p '^Added.*source$'
[Added application source
Ignore-this: 7403e5fb594ec9403d26d8c01ffdcb3c
] adddir ./src
addfile ./src/hi.rb
hunk ./src/hi.rb 1 This named patch contains
+puts "Hi" three "primitive patches"

Pushing patches
repo_b % darcs push
Pushing to "/Users/ashleymoran/Documents/
PatchSpace/Presentations/darcs/repos/repo_a"...
Shall I push this patch? (1/2) [ynWvplxdaqjk],
or ? for help: y
* More hellos
Shall I push this patch? (2/2) [ynWsfvplxdaqjk],
or ? for help: n
Finished applying...
Push successful.

View remote patches
repo_b % darcs changes --repo=../repo_a


Spot a recorded mistake
repo_b % darcs whatsnew --summary hi.txt
What's new in "hi.txt": No changes!
repo_b % cat hi.txt
Hello, darcs Already recorded this in a patch
How are you?

repo_b % sed -ie 's/you/you today/' hi.txt
repo_b % cat hi.txt
Hello, darcs
How are you today?

hunk ./hi.txt 2
-How are you? We want this patch instead
+How are you today?

Amend-record a patch
repo_b % darcs amend-record
* More hellos
Shall I amend this patch? [yNvpxq], or ? for
help: y
hunk ./hi.txt 2 You can amend-record any patch
-How are you? that isn't depended upon
+How are you today?
Shall I add this change? (1/1) [ynWsfvplxdaqjk],
or ? for help: y
Finished amending patch:
* More hellos

View amended patch
Before amend-record
repo_b % darcs annotate -p 'More'
[More hellos
Ignore-this: 27105a11a78c889107399e21d7b9dea0
] hunk ./hi.txt 2
+How are you?
After amend-record
repo_b % darcs annotate -p 'More hellos'
[More hellos
Ignore-this: 3c7d315c69e36a3f3faad64e9074b6e9
] hunk ./hi.txt 2
+How are you today?

Push remaining patches
repo_b % darcs push -a
Push successful.
Once you've pushed a patch it would
be considered "wild". Don't amend-
record a patch that has been pushed!

Recording unwanted…
repo_b % echo 'exit false' >> src/hi.rb
repo_b % cat src/hi.rb
puts "Hi"
exit false
hunk ./src/hi.rb 2
+exit false
repo_b % darcs record -a -m 'Make hi.rb fail'
Finished recording patch 'Make hi.rb fail'
repo_b % darcs changes --last 1
* Make hi.rb fail
No changes!

…so unrecording…
repo_b % darcs unrecord
* Make hi.rb fail
Shall I unrecord this patch? (1/4)
* More hellos
Shall I unrecord this patch? (2/4)
[ynWsfvplxdaqjk], or ? for help: d
Finished unrecording.
d for "done" - skip
remaining patches

…and carrying on.
Patch removed
* More hellos

puts "Hi" Working copy unmodiﬁed
exit false

hunk ./src/hi.rb 2 Change can be re-recorded
+exit false

Recording unwanted…
repo_b % darcs record -a -m 'Make hi.rb fail'
Finished recording patch 'Make hi.rb fail'

repo_b % darcs changes -p 'fail'
* Make hi.rb fail
To save making a new patch,
I'm just re-recording the last

…REALLY unwanted…
repo_b % darcs obliterate
* Make hi.rb fail
Shall I obliterate this patch? (1/4)
* More hellos
Shall I obliterate this patch? (2/4)
[ynWsfvplxdaqjk], or ? for help: d
Finished obliterating.

…and it's REALLY gone.
* More hellos

repo_b % darcs changes -p 'fail'

puts "Hi" Patch never existed!

Check repos are in sync
repo_b % darcs push --dry-run ../repo_a
Would push to "/Users/ashleymoran/Documents/
No recorded local changes to push!

repo_b % darcs pull --dry-run ../repo_a
Would pull from "/Users/ashleymoran/Documents/
No remote changes to pull in!

--dry-run is useful for seeing changes

Record a change in repo A
repo_b % cd ../repo_a

repo_a % echo 'Yo dude' > hi.txt

repo_a % darcs record -a -m 'Change greeting'
Finished recording patch 'Change greeting'

repo_a % darcs annotate -p 'greet'
[Change greeting
Ignore-this: b41771e45b0a2277729dae96768e232b
] hunk ./hi.txt 1
-Hello, darcs
-How are you today?
+Yo dude

Record a change in repo B
repo_a % cd ../repo_b

repo_b % echo 'Aup youth' > hi.txt

repo_b % darcs record -a -m 'Update salutation'
Finished recording patch 'Update salutation'

repo_b % darcs annotate -p 'salut'
[Update salutation
Ignore-this: cfe070e308bb4a14e010a6ea0d15be72
] hunk ./hi.txt 1
-Hello, darcs
-How are you today?
+Aup youth

Pull in the change: conﬂict!
repo_b % darcs pull
darcs remembers remote repos used
Pulling from "/Users/ashleymoran/Documents/
* Change greeting
Shall I pull this patch? (1/1) [ynWsfvplxdaqjk],
or ? for help: y
Backing up ./hi.txt(-darcs-backup0)
We have conflicts in the following files:
./hi.txt
Finished pulling and applying.

Repo in conflict state
repo_b % ls
_darcs

hi.txt-darcs-backup0
src
hi.txt

hi.txte
repo_b % cat hi.txt
v v v v v v v
Aup youth Conflicted working copy file
*************
Yo dude
^ ^ ^ ^ ^ ^ ^
repo_b % cat hi.txt-darcs-backup0 Original local file
Aup youth
repo_b % cat hi.txte
Hello, darcs
Pre-conflict file
How are you?
The darcs team wants to improve conflict marking

Resolve the conflict
After much discussion, the
correct form is found
repo_b % echo 'Aup dude' > hi.txt

repo_b % darcs record -a -m 'Correct greeting'
Finished recording patch 'Correct greeting'

repo_b % rm hi.txt-darcs-backup0 hi.txte

The 'Correct greeting' patch depends
upon the conflicting primitive patches,
and resolves the conflict

What's new w.r.t. repo A?
repo_b % darcs push --dry-run
Would push to "/Users/ashleymoran/Documents/
Would push the following changes:
* Update salutation

* Correct greeting

Making no changes: this is a dry run.

Repo A needs our original patch and
also the conﬂict resolution patch

Resolve the conﬂict
repo_b % darcs push -a
Push successful.

Creating a fresh repo
repo_b % mkdir ../repo_c
repo_b % cd ../repo_c
repo_c % darcs init

Pulling from Repo A
repo_c % darcs pull ../repo_a
or ? for help: y
Shall I pull this patch? (2/6) [ynWvplxdaqjk],
or ? for help: d

Repo C is now 'primed' to pull from
repositories generated from Repo A

Pulling from Repo B
repo_c % darcs pull ../repo_b
Shall I pull this patch? (1/5) [ynWvplxdaqjk],
or ? for help: y
* More hellos
or ? for help: d

I didn't need to pull the ﬁrst patch. I could
have pulled any patch without dependencies.
This will be explained later.

What's left in Repo A?
repo_c % darcs pull --dry-run ../repo_a
Would pull from "/Users/ashleymoran/Documents/
Would pull the following changes:
* More hellos
* Change greeting
* Update salutation
* Correct greeting
Making no changes: this is a dry run.
We can push and pull from Repo A, B or C in any
direction - none of them are special to darcs

A depended-on patch
repo_c % darcs pull ../repo_a
* More hellos
or ? for help: n
Skipped pull of 3 changes.
You don't want to pull any patches, and that's
fine with me!

darcs knows that all the remaining
patches depend on this one, so doesn't
attempt to pull them

The future of darcs
Ian Lynagh is doing a re-implementation
of the darcs patch algebra (and proof of
the patch theory) under the project name
Camp
http://projects.haskell.org/camp/
Camp has a good demonstration to
visualise patch vs chronological history
http://projects.haskell.org/camp/unique
Let's watch the video =)

What's not covered? (1)

Deleting ﬁles - just throw away and darcs
sees they should be removed
darcs mv - renaming ﬁles
darcs revert - discarding your working
copy changes
darcs unrevert - getting them back!

What's not covered? (2)
darcs rollback - generating a patch to
undo a change
darcs tag - marking a snapshot version of
a repository you can easily get back to
darcs send - generating a patch bundle ﬁle
you can send by email etc
darcs apply - applying a patch bundle

Repositories vs branches
In darcs, a branch and a repository are the
same thing
You can also have "branches" identiﬁed by
patch keywords, eg "[BUG61] ..."
You can view this presentation as if
Repo A is remote; Repo B is local
Repo A is local; Repo B is a branch
Replace repo_a with user@remote:repo_a

Centralised repositories

You can nominate repositories as a
"central repository", but this is only for
convenience
Hosting is available:
http://patch-tag.com/

darcs limitations
Some darcs operations are much slower
than the equivalents in other revision
control systems
Could be a problem with very large repos
Patch theory is still not fully understood,
so edge case bugs may be lurking
Mainly suitable for small-medium teams,
or where a small team can help integrate
patches (eg OSS projects)

Why I use darcs
Conceptually simple - it's just repositories
and patches
Smart - handles complex merge problems
Easy to use - hides the complexity with a
friendly interface
Interactive - always presents me with the
choices I need
Flat learning cur ve - took no time to learn

References

http://nwrug.org/events/july09/
http://darcs.net/manual/
http://wiki.darcs.net/
http://blog.interlinked.org/tutorials/
darcs.html

Contact

Slides prepared by Ashley Moran
ashley.moran@patchspace.co.uk
www.patchspace.co.uk
Creative Commons licensed - contact me
for commercial use

NWRUG July 2009 - Darcs

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (9)

Semelhante a NWRUG July 2009 - Darcs

Semelhante a NWRUG July 2009 - Darcs (20)

Mais de PatchSpace Ltd

Mais de PatchSpace Ltd (10)

Último

Último (20)

NWRUG July 2009 - Darcs