RosettaStone

Translations

Initialising and cloning

concept darcs git hg bzr
new repository init init init init
copy repository get (aka clone) clone clone checkout
branch see checkout branch branch branch
switch branch na [1] checkout update ?
  • [1] No in-repo branching yet, see issue555

Adding, moving, removing files

concept darcs git hg bzr
track file add add add ?
copy file na just copy it, git might notice copy na
move/rename file move (aka mv) mv rename (aka mv) mv

Inspecting the working directory

concept darcs git hg bzr
working dir status whatsnew -s status status status
high-level local diff whatsnew na na na
diff local diff [1] diff diff diff
  • [1] we tend to use the high-level local diff (darcs whatsnew) instead. This displays the patches themselves (eg ‘mv foo bar’) and not just their effects (eg ‘rm foo’ followed by “add bar”)

Committing

concept darcs git hg bzr
commit locally record commit commit commit –local
commit to repo see push/send see push see push commit
amend commit amend-recor d commit –amend ? ?
tag changes/revisions tag tag tag tag

See below for comments on record vs commit.

Inspecting the repository history

concept darcs git hg bzr
log changes (aka log) log log log
manifest show files ls-files manifest ls
summarise outgoing changes push –dry-run [1] ? outgoing missing –mine-only
summarise incoming changes pull –dry-run log ..origin/mast er incoming missing –theirs-only
diff repos or versions diff diff incoming /outgoing/dif f -r diff
blame/annotate annotate blame? annotate ?
  • [1] if “pushing” to an HTTP repository, this will emit a warning that pushing over HTTP does not work, but the dry-run will still work

Undoing

concept darcs git hg bzr
revert a file revert foo checkout foo revert foo
revert full working copy revert reset –hard revert -a revert
undo commit (leaving working copy untouched) unrecord reset –soft rollback ?
amend commit amend-recor d commit –amend ? ?
destroy last patch/ changeset obliterate delete the commit strip [1] uncommit [2]
destroy any patch/ changeset obliterate rebase -i, delete the commit strip [1] ?
create anti-changeset rollback revert backout
  • [1] requires extension (mq for strip)
  • [2] this offers you a chance to restore the commit; see issue75

Collaborating with others

concept darcs git hg bzr
update from repo see pull remote update pull -u update
pull pull pull pull update
push push push push push
send by mail send send-email email [1] merge-directive –mail-to
  • [1] requires extension (patchbomb for email)

Advanced usage

concept darcs git hg bzr
port commit to X na [2]_ rebase/cherry -pick transplant ?

* [2] usually not needed because of patch reordering, but see issue938 and http://lists.osuosl.org/pipermail/darcs-users/2010-August/024924.html if you really need darcs rebase now.

Discrepencies between DVCS

Git has the notion of an index (which affects the meanings of some of the commands), Darcs just has its simple branch-is-repo-is-workspace model.

Hg’s rollback only works on one level and is not reversible. On the other hand, it seems to have an interesting, very general, idea of undoing transactions (general in that there are a lot of commands which are “transactional”). It should be studied a bit more carefully.

Superficial differences:

  • git revert is like darcs rollback
  • git reset is like darcs revert

See also DifferencesFromOtherDVCS

Recommendations for unification

Note that there are no current plans to rename commands. The following is some idle speculation on how darcs (and other revision control systems) can make it easier for users to go from one system to another. In particular, we want to be careful to avoid forcing things to have the same name if they actually have subtly different meanings.

Quoting Stephen Turnbull

In general, I think that application of database terminology would be
a good idea, with the exception of "commit" because of the historical
context of CVS, and the very strong intuition that recording locally
doesn't commit you to anything (cf. the rebase controversy, where
everybody agrees that local rebasing is a mere peccadillo or even
beneficial, while rebasing a branch that has been published is equated
to smoking in an elevator filled with pregnant women).

General principles

There will be no swapping of command names in any system. That would just cause too much confusion. If any change were to happen, it would likely have to involve converging to a new set of consensus commands. This requires cooperation from all revision control systems.

Darcs

  • rename whatsnew -s to status (see issue182)

  • rename get to clone

    • We should be careful here to make sure we know what we’re doing with branching first (see issue555 )
  • rename changes to log

  • rename rollback to new “backout”

    • Eric originally suggested “repeal”, but everybody hated it, including Eric
    • “reverse” has also been suggested (although it sounds a lot like revert, which could be bad)
    • “invert” is another possibility (but maybe that has the same problem as “reverse”)
    • “backout” has the nice property of already being used in the same way by Hg

darcs record stays

Note: one command we are making a point to keep is “darcs record” (as opposed to darcs commit). We think it’s important to preserve the distinction between saving a change locally and publishing that change somewhere.

Also, here is what you get when you type in “darcs commit”:

This command does not do anything.
If you want to save changes locally, use the `darcs record' command.
If you want to save a recorded patch to another repository, use the
`darcs push' or `darcs send' commands instead.

Others

We may not have much say in what others name things, but these may help build a consensus command set

  • git:rename revert to new “backout” (or whatever we collectively decide is a good name)
  • everybody: rename commit to “record” ;-)
  • bzr: rename uncommit to obliterate (potential source of confusion?)

References