notes-computer-programming-hg

Warning: i am still learning hg (mercurial), so some of the following may be incorrect.

Mercurial vs. git

i haven't used git so i dunno. Things i read suggest that the main differences are currently:

• Mercurial's UI is simpler -- git has a tendency to use lots of command switches to do different things, whereas mercurial uses different commands (see http://stevelosh.com/blog/2010/01/the-real-difference-between-mercurial-and-git/ , http://jonchu.posterous.com/16445171 )
• There's some stuff i don't understand that makes git slightly more powerful for experts who are doing fancy stuff involving cherrypicking patches (see http://lucumr.pocoo.org/2010/8/17/git-and-mercurial-branching/ )
• Git is better at really large repos (large in terms of the disk storage space required to store individual versions) ( http://blog.extracheese.org/2010/05/why-i-switched-to-git-from-mercurial.html )
• Github is better than bitkeeper

Note that the unofficial hg-git mercurial extension lets you access git repos with an hg client.

Basic mercurial terms

• Repository (repo), a storage space for versions
• Working directory, a place where individual versions go

Basic mercurial commands

• hg init __create new repo out of current directory__
• hg clone __get a copy of an existing repo from elsewhere__
• hg status __show which files have been modified, which files are unversioned, etc__
• hg add __start versioning a new file__
• hg rm __stop versioning a file, and delete it__
• hg mv __move a file, keeping hg in the loop__
• hg pull -u __get updates from upstream__
• hg ci __commit changes from working directory into local repo__
• hg push __push changes from local repo upstream__
• hg merge __do this after you pull an update that includes a "multiple head", that is, when someone else pushed their update before you pushed yours; be sure and resolve and conflicts after you do this__

Intermediate mercurial commands

• hg log __look at the log__
• hg revert __revert the state of a given file or directory to last revision__
• hg diff __diff files or directories between revisions or between working dir state and revisions__
• hg incoming __show pending updates waiting to be pulled from upstream__
• hg pull __pull updates from upstream into the local repo, but don't update the working directory yet__
• hg update __update the working directory__
• hg outgoing __show pending updates to waiting to be pushed to upstream__
• hg glog __ascii art version of log (requires graphlog extension)__

Also, the 'color' extension is easy and colorizes the output of some commands.

Note that any mercurial command can be abbreviated to the shortest disambiguous prefix.

Advanced mercurial stuff

• hg bisect __finds the first changeset that breaks a test__
• bookmarks: http://stevelosh.com/blog/2009/08/a-guide-to-branching-in-mercurial/ , http://mercurial.selenic.com/wiki/BookmarksExtension
• branches: http://stevelosh.com/blog/2009/08/a-guide-to-branching-in-mercurial/
• mq stuff (see Mercurial Queues Extension, below)
• subrepo extension: http://mercurial.selenic.com/wiki/Subrepository
• hgk extension: hg view __start interactive viewer__

Serving a repo over http

• hg serve __serve one repo (built-in webserver)__
• hgwebdir: __serve many repos (CGI)__
• notify extension: send email notifications when a repo is changed.

Top mercurial extensions

See http://mercurial.selenic.com/wiki/ExtensionHitlist , http://stackoverflow.com/questions/1869040/what-are-the-best-and-must-have-hg-mercurial-extensions

Mercurial Queues Extension

When you are working on something you want to commit intermediate states frequently so that you can revert to previous states if you change your mind; or so that you can stop working on feature A, revert to a version that runs, and do something else, then go back to working on feature A.

However, if you do this, it clutters up the repo with all these tiny commits which have no permanent value, which don't pass the testing suite, and whose content is not very well described by their commit messages. This may be annoying to you and the other programmers on the project later on.

So, Mercurial Queues adds another layer of versioning. While working on something, you save state as versioned (but temporary) "patches". When you are done, you make an actual commit, and forget about the patches.

See http://mercurial.selenic.com/wiki/MqTutorial , 'hg help mq', http://mercurial.selenic.com/wiki/MqExtension

Basic mq commands

• hg init --mq __start using mq__
• hq qnew NAME __create a new patch__
• hg qrefresh __'commit' to current patch__
• hg qpop -a __undo all patches; do this before hg pull -u__
• hg qpush -a __redo all patches; do this after hg pull -u__
• hg qfinish -a __convert all patches into actual commits__

Intermediate mq commands

• hg qdiff __show diff between last revision in the local repo and working dir__
• hg qtop __show current patch name__
• hg qapplied __list of patches currently applied to the working dir__ (meaning that, the sum of these patches, plus any unapplied changes in the working dir, equals the diff between the last revision in the local repo and the working directory; neither hg status nor hg diff will show changes that have been 'commited' to a patch)
• hg qseries __list of patches currently in the queue__
• hg qpop __undo current patch ("pop" off the patch "stack"; use this when you want to temporarily revert a patch so that you can work on something else starting from a previous state)__
• hg qpush __redo current patch (popped patches are not forgotten, as you can see with qunapplied or qseries)__
• hg qgoto __push or pop patches until named patch is at top of stack__
• hg qrm __delete a patch (it must be unapplied)__

Advanced mq commands

• hg qnew -m "DESCRIPTION" or hg qrefresh -m "DESCRIPTION"
• hg -R .hg/patches COMMAND __execute COMMAND on the patch repo (which is at .hg/patches)__
• hg rebase --mq __i don't know what this does but it used to be called hg restore so i guess it's useful__
• hg qimport __import a patch from a patch file (you can 'export' just by looking at the patch files in .hg/patches)__
• hg diff -r $(hg parents -r qbase --template '{rev}') -r qtip __Export all applied patches as a single patch__
• hg qpop -a; hg qpush; hg qunapp

• hg qrename