Mercurial intro
Upcoming SlideShare
Loading in...5
×
 

Like this? Share it with your network

Share

Mercurial intro

on

  • 667 views

 

Statistics

Views

Total Views
667
Views on SlideShare
667
Embed Views
0

Actions

Likes
0
Downloads
2
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

Mercurial intro Presentation Transcript

  • 1. Mercurial For devs...
  • 2. What will we talk about?● The .hgrc● A Stack of Patches● Basic Commands● Branching, pushing, pulling● Howtos
  • 3. Assumptions● You have some programming knowledge● You know the basics of some version control system ○ git ○ svn ○ cvs ○ mercurial ○ ...
  • 4. .hgrc! Who has no .hgrc?
  • 5. .hgrc!
  • 6. Why .hgrc?● Username● Extensions● Aliases● Other settings● Example: ○ http://confluence.incubaid. com/display/ENG/Incubaid+Starter+Kit
  • 7. What is .hgrc● Configuration for your Mercurial● INI file format ○ # Comments ○ [sections] ○ key = value
  • 8. Minimal .hgrc: Username[ui]username = John Doe <john.doe@example.com>
  • 9. .hgrc: Extensions● Mercurial without extensions is barely useable● Small core, but easy to extend● Extensions add some sugar● Python scripts ○ Write your own!
  • 10. .hgrc: Extensions[extensions]pager = # pipe through less automaticallycolor = # Color outputgraphlog = # ASCII art graphical logsfetch = # Pull-and-merge, use with caremq = # Strip, flexible commit queueshighlight = # syntax highlighting in hgweb
  • 11. .hgrc: aliases[alias]blame = annotate -uout-diff = out -pvMin-diff = in -pvM# Show the diff of a given changeset IDshow = log -p -v -r
  • 12. How to think about Mercurial Its a stack of patches with downward links between them
  • 13. A Stack of PatchesWorking directorycommit @ 4:ch4ch4: Change number 3 Parent: ch3ch3 tag: tip Top of the stack Patch Save Time 3:ch3ch3: Merge in Alices work Stack index Parent: ch2ch2 Clone- Parent: al1al1 dependent! Node ID 2:ch2ch2: Change number 2 Unique! Parent: ch1ch1 1:al1al1: Alices changes parent: ch1ch1 is-child-of 0:ch1ch1: Change number 1Root commit Parent: ch0ch0Identifies a repository
  • 14. What is a commit?● Diff● Metadata ○ timestamp ○ user SHA1 Unique Commit ○ branch? ID ○ parent(s): 1 or 2 ○ ...● If you change any of these fields: ○ commit ID will change ○ you create a different commit!
  • 15. Cause of all those merges Local repository status: 1:ch2ch2: Change number 2 Parent: ch1ch1 0:ch1ch1: Change number 1
  • 16. Cause of all those merges Pull from Alices repository: 2:al1al1: Alices changes parent: ch1ch1No re-ordering can 1:ch2ch2: Change number 2 Parent: ch1ch1happen without alteringthe tags and therefore theunique hashes of thecommits! 0:ch1ch1: Change number 1
  • 17. Cause of all those merges 2 heads! 2:al1al1: Alices changes parent: ch1ch1 1:ch2ch2: Change number 2 Parent: ch1ch1 0:ch1ch1: Change number 1We want one head!
  • 18. Cause of all those merges 3:ch3ch3: Merge in Alices work Parent: ch2ch2 Parent: al1al1 2:al1al1: Alices changes parent: ch1ch1 1:ch2ch2: Change number 2 Parent: ch1ch1 0:ch1ch1: Change number 1-> We need to merge. :-(
  • 19. Quiz 1● What is .hgrc good for?
  • 20. Quiz 1● What is .hgrc good for? ○ Username ○ Extensions ○ Aliases ○ Much, much more
  • 21. Quiz 1● What is .hgrc good for? ○ Username ○ Extensions ○ Aliases ○ Much, much more● How should you imagine a Mercurial repository?
  • 22. Quiz 1● What is .hgrc good for? ○ Username ○ Extensions ○ Aliases ○ Much, much more● How should you imagine a Mercurial repository? ○ As a stack of patches.
  • 23. Basic Commands● help● clone● init● add/remove/addremove● cp/rename/mv● status● diff● commit
  • 24. Help!● hg help: General help ○ List of commands ○ List of extensions ○ Additional help topics (advanced stuff)● hg help <command> ○ hg <command> --help
  • 25. Cloning a repository● hg clone <remote> <foldername>● Creates a .hg folder in <foldername>● Downloads all the patches/commits from <remote>● Checks out the files of the last commit on the default branch on your disk, in <foldername>
  • 26. Init: Creating a new repository● hg init <foldername>● Creates a .hg folder in <foldername> ○ No commits yet ○ No changes yet
  • 27. Add/Remove/Addremove● hg add <path> ○ enables <path> for committing● hg rm <path> ○ disables <path> for committing● hg addremove <path> ○ "Add all new files and remove all missing files from the repository." ○ Use with care (.hgignore!)● Paths either absolute or relative to $PWD! ○ <> hg status output
  • 28. cp/rename/mv/move● Avoid having to add/rm● hg cp● hg rename ○ Aliases: mv, move
  • 29. Status● Show which files are: ○ Added (A) ○ Removed (R) ○ Modified (M) ○ Missing (!) - use hg rm ○ Not tracked (?) - use hg add● Paths relative to repository root (annoying) ○ Try hg status . ○ Mercurial 1.7 or higher: ■ Alias: stat = !hg status $($HG root) $HG_ARGS
  • 30. .hgignore● Tell Mercurial to ignore files in your repository ○ mycode.pyc ○ README.txt~ ○ mycode.py.orig ○ mycode.py.rej ○ ...● 2 ways of matching ○ Regex (default) ■ .pyc$ or re:.pyc$ ○ glob (~bash) ■ glob:**.pyc● Located in `hg root`
  • 31. .hgignore: Examplesyntax: globdoc/*.auxdoc/_build/htmldist/*arakoon.native**.pycsyntax:regexp^_build~$
  • 32. locate: test a pattern● "locate files matching specific patterns"● hg locate "glob:**.py" ○ The quotes are needed to avoid your shell expanding the *● Only prints files under Mercurial control ○ Like find, but limited to tracked files.
  • 33. Diff: what did I change?● hg diff● Changed files: ○ Show diff with previously committed version● Added files: ○ Show content● Removed files: ○ Show content● Specify <path> ○ Diff only that file/those files ○ Can use re: and glob:● USE COLOR !!!
  • 34. Color extension● .hgrc● [extensions] color =● Colors can be customized● Adds color to almost all commands that have output ○ status ○ diff ○ log ○ ...
  • 35. Commit: Create a new commit● hg commit ○ Username ■ from .hgrc (preferably!) ■ -u "Joske Vermeulen <joske@incubaid.com>" ○ Commit message ■ in editor (default) ■ -m "My commit" ○ Files ■ Default: everything shown as A/R/M in status ■ Use -I and -X for more control (re, glob)● Creates a new commit● Use nice commit messages
  • 36. Log: check the history● hg log● Order: stack of patches!● Spammy? Theres an extension for that! [extensions] pager = [pager] pager = less -R attend = annotate, cat, df, diff, >>glog, help, in-diff, incoming, >>log, out-diff, outgoing, qdiff, >>show, tip, grep
  • 37. Graph log● Useful when branching, merging, ...● ASCII art graphs!● Need to enable the extension ○ [extensions] graphlog =● hg glog● @ marks the working directory commit
  • 38. Example glog output:| o changeset: 3246:1f56e1265e40| | parent: 3245:96b848f10790| | | parent: 3243:72b775711468| | | user: Mohammed Azmy <mazmy@aserver.com>| | | date: Thu Sep 13 10:36:17 2012 +0200| | | summary: Automatic merge| | || | @ changeset: 3245:96b848f10790| | | parent: 3236:c544f3aa38cc| | | user: Mohammed Azmy <mazmy@aserver.com>| | | date: Thu Sep 13 10:35:49 2012 +0200| | | summary: return empty string if key is none| | |o | | changeset: 3244:ed5095ad82a8|/ / user: Jens Geiregat <jens.geiregat@incubaid.com>
  • 39. Quiz 2: basic hg commands● Start tracking an untracked file?
  • 40. Quiz 2: basic hg commands● Start tracking an untracked file? ○ hg add <path>
  • 41. Quiz 2: basic hg commands● Start tracking an untracked file? ○ hg add <path>● Print the root of the repository youre in?
  • 42. Quiz 2: basic hg commands● Start tracking an untracked file? ○ hg add <path>● Print the root of the repository youre in? ○ hg root
  • 43. Quiz 2: basic hg commands● Start tracking an untracked file? ○ hg add <path>● Print the root of the repository youre in? ○ hg root● Commit only one file when multiple are changed?
  • 44. Quiz 2: basic hg commands● Start tracking an untracked file? ○ hg add <path>● Print the root of the repository youre in? ○ hg root● Commit only one file when multiple are changed? ○ hg commit -I <path>
  • 45. Quiz 2: basic hg commands● Start tracking an untracked file? ○ hg add <path>● Print the root of the repository youre in? ○ hg root● Commit only one file when multiple are changed? ○ hg commit -I <path>● Command to show an ASCII art log graph?
  • 46. Quiz 2: basic hg commands● Start tracking an untracked file? ○ hg add <path>● Print the root of the repository youre in? ○ hg root● Commit only one file when multiple are changed? ○ hg commit -I <path>● Command to show an ASCII art log graph? ○ hg glog
  • 47. Quiz 2: basic hg commands● Start tracking an untracked file? ○ hg add <path>● Print the root of the repository youre in? ○ hg root● Commit only one file when multiple are changed? ○ hg commit -I <path>● Command to show an ASCII art log graph? ○ hg glog● Mark for the working directory commit?
  • 48. Quiz 2: basic hg commands● Start tracking an untracked file? ○ hg add <path>● Print the root of the repository youre in? ○ hg root● Commit only one file when multiple are changed? ○ hg commit -I <path>● Command to show an ASCII art log graph? ○ hg glog● Mark for the working directory commit? ○ @
  • 49. Branching, pushing, pulling● branch● update● identify● push● pull● incoming, outgoing
  • 50. Branching...● Not very flexible in Mercurial ○ Unique branch names ○ No branch renames ○ Branch name must be chosen before first commit on that branch ○ ...● Just adds a "branch=name" to the metadata of a commit.● Default branch has no "branch=default"● Interesting comparison: http://stevelosh.com/blog/2009/08/a-guide-to-branching-in-mercurial/
  • 51. Back to the stack of patches... 8:cb2cb2: Also on the branch Parent: cb1cb1 branch: mybranch tag: tip hg update mybranch Patch Save Time 7:ch5ch5: Change number 5 Parent: ch4ch4hg update default 6:cb1cb1: Branching! Parent: ch3ch3 branch: mybranchhg update 4 && hg branch mybranch 5:ch4ch4: Change number 4 Parent: ch3ch3 4:ch3ch3: Change number 3 Parent: ch2ch2
  • 52. Branch-related commands● hg branch ○ What branch am I on?● hg branches ○ What branches are there?● hg branch <name> ○ Create a branch with <name>
  • 53. Update● Changes the working directory commit (@) ○ hg update <branchname> ■ Go to the last commit on branch <branchname> ○ hg update <rev> ■ Go to revision <rev>● Discard local changes (danger, no backup!) ○ hg update --clean ... ○ Forces the update
  • 54. Identify● Prints the working directory commit (@)● hg identify c640c961a243 tip
  • 55. Push● Send changesets not yet at <remote> to <remote>● hg push ○ Push to default● hg push ssh://hg@bitbucket.org/incubaid/pylabs-core-5.1 ○ Explicit target● hg push default ○ Push to default path explicitly. ○ Define default (and others) in .hg/hgrc● Protocol: SSH or HTTP (or local)
  • 56. Push: shortcuts.hg/hgrc:[paths]default = ssh://hg@bitbucket.org/incubaid/pylabs-core-5.1private = ssh://hg@bitbucket.org/geiregaj/pylabs-core-5.1-jens
  • 57. hg paths● Prints the named paths for the repository: ○ $ hg paths default = ssh://hg@bitbucket.org/incubaid/pylabs-core-5.1 private = ssh://hg@bitbucket.org/geiregaj/pylabs-core-5.1-jens
  • 58. Push -b● hg push -b default ssh://...● Push one branch ○ Keeps the <remote> clean ○ Push your branch to a private repository, after merge push to the common repository
  • 59. hg duw● [alias] duw = push -r .● Pushes your working directory commit (@)
  • 60. Pull● hg pull● hg pull default● hg pull ssh://hg@bitbucket.org/incubaid/pylabs-core-5.1● Downloads the changesets that are on <remote> but not on <local>● Shortcut: hg pull -u ○ == hg pull && hg update● Tip will be the newest of the pulled commits
  • 61. Incoming, outgoing● Show commits that would be pulled or pushed● Useful as a quick check without the danger of pulling things you dont want yet.
  • 62. Quiz 3● Why do you need to commit to create a branch?
  • 63. Quiz 3● Why do you need to commit to create a branch? ○ Because branches only really exist in the commits, as a tag. No commit means no tag. No tag means no branch.
  • 64. Quiz 3● Why do you need to commit to create a branch? ○ Because branches only really exist in the commits, as metadata. No commit means no metadata. No metadata means no branch.● How to print all branch names?
  • 65. Quiz 3● Why do you need to commit to create a branch? ○ Because branches only really exist in the commits, as metadata. No commit means no metadata. No metadata means no branch.● How to print all branch names? ○ hg branches
  • 66. Quiz 3● Why do you need to commit to create a branch? ○ Because branches only really exist in the commits, as metadata. No commit means no metadata. No metadata means no branch.● How to print all branch names? ○ hg branches● How to find out what your working directory commit is?
  • 67. Quiz 3● Why do you need to commit to create a branch? ○ Because branches only really exist in the commits, as metadata. No commit means no metadata. No metadata means no branch.● How to print all branch names? ○ hg branches● How to find out what your working directory commit is? ○ hg identify ○ hg glog and search for the @
  • 68. Howtos● Merge● Discard changes● Collaborate● Feature branches● Commit message template● (Bitbucket) SSH keys● Remove a commit● Undo a commit
  • 69. How to Merge● This is where things typically go wrong. ○ Merge direction... ○ > 2 heads ○ Conflicts (oh noes!)
  • 70. Merge Direction: Goal● A small diff! ○ Keeps your tools from choking on HUGE diffs● From hg merge --help ○ The current working directory is updated with all changes made in the requested revision since the last common predecessor revision.
  • 71. Merge Direction1. Create your local commit2. Pull in the latest changes from <remote>3. Check the situation with a. hg glog b. hg heads4. Decide on the merge direction5. hg update <base> (if needed)6. hg merge7. Check the merge (tests?)8. Commit
  • 72. Merge Direction 9:ch7ch7: Change number 7 Parent: ch6ch6 8:ch6ch6: Change number 6 Parent: ch5ch5Pulled 7:ch5ch5: Change number 5 Parent: ch4ch4 @ 6:abcabc: My change Parent: ch2ch2 5:ch4ch4: Change number 4 Parent: ch3ch3 4:ch3ch3: Change number 3 Parent: ch2ch2
  • 73. Merge Direction hg update ch7ch7 @ 9:ch7ch7: Change number 7 Parent: ch6ch6 8:ch6ch6: Change number 6 Parent: ch5ch5Pulled 10 changes 7:ch5ch5: Change number 5 Parent: ch4ch4 @ 6:abcabc: My change Parent: ch2ch2 5:ch4ch4: Change number 4 Parent: ch3ch3 1000 changes 4:ch3ch3: Change number 3 Parent: ch2ch2
  • 74. @ 9:ch8ch8c: Merge Parent: ch7ch7 Merge Direction Parent: abcabc 9:ch7ch7: Change number 7 Parent: ch6ch6 hg merge hg commit 8:ch6ch6: Change number 6 Parent: ch5ch5 -m "Merge"Pulled 7:ch5ch5: Change number 5 Parent: ch4ch4 6:abcabc: My change Parent: ch2ch2 5:ch4ch4: Change number 4 Parent: ch3ch3 4:ch3ch3: Change number 3 Parent: ch2ch2
  • 75. Merge: > 2 heads● Mercurial can only merge 2 heads / commit● To merge > 2 heads, merge multiple times ○ Choose head with most changes (biggest diff) ○ hg update <bighead> ○ hg merge <smallerhead> ○ hg commit ○ -> repeat
  • 76. Merge: conflicts● kdiff3 ○ 3-way merge tool ○ Powerful ○ Simple to use ○ Install it and configure it in your .hgrc ■ or use my example config...
  • 77. Merge: conflicts Next unmerged conflict Choose ● Kdiff3! lineCommon ancestor Local RemoteResult: Edit by clicking A/B/C or by manually editing the text
  • 78. Merge: conflicts● Kdiff3 workflow: ○ Fix all unmerged conflicts ■ use triple arrows to find them ■ A/B/C or manual edit ○ When all unmerged conflicts are resolved ■ Click save ■ Exit kdiff3
  • 79. Howto: discard changes● You changed or removed a file● But want to restore it to how it looked in the last commit ○ hg revert <path>● Shortcut: revert everything: ○ hg revert --all● The content before the revert is saved with suffix .orig● Revert to a specific revision ○ hg revert -r abcabc <path>
  • 80. Howto: Collaborate● Avoid working on the same files at the same time ○ Same for moving files that other people are working on● Push your code often ○ What if you lose your laptop? ○ If you dont want to push to the main repository, create a private clone on Bitbucket● Merge with care● But... ○ what if Bitbucket goes down?!
  • 81. Howto: Collaborate
  • 82. Howto: Collaborate● hg serve to the rescue!● Runs an HTTP server ○ Browse your repository ■ Useful for quick reviews! ○ Pull code from it ■ hg pull http://my.ip.com:8000/● hg serve is built-in
  • 83. Howto: Collaborate● Default push/pull protocol: SSH● Allows pushing (hg serve does not, by default)● hg push ssh://user@host/home/user/repo/path/ ○ Use SSH keys
  • 84. Howto: Feature Branches● Upside: ○ Develop your feature without messing up the default branch of the repository● Downside ○ amount of branches might become very large... ■ Close your feature branches ■ Use clones, bookmarks, ...
  • 85. Howto: Feature BranchesFeature merged intodefault D6No choice about merge directionhere. D5 B5 Use --close-branch D4 B4 Merge latest default D3 B3 hg merge default B2 D2 B1 Feature branch D1 Default D0
  • 86. Howto: commit message template● .hgrc: ○ [ui] username = Jens Geiregat <...> editor = /usr/bin/vim -c "r ~/.hgtemplate" ○ vim command r[ead] <path>● .hgtemplate: ○ """ Reference: Signed-off-by: """
  • 87. Howto: (Bitbucket) SSH keys● Easier pushing and pulling from Bitbucket● Easy to set up ○ http://bit.ly/S4l1ly● Invest 2 minutes, gain years of easier Bitbucket interaction.● Also useful for non-Bitbucket servers ○ Use ssh-copy-id to publish your public key to a remote machine
  • 88. Howto: Remove a commit● Removes a commit and every commit depending on it ○ DANGER! ○ Creates a backup in .hg/strip-backup as a bundle ○ Can only be used when the strip happens on ALL clones that contain the stripped commit(s).● Part of the mq extension: ○ [extensions] mq =● Bitbucket can strip too ○ Part of the admin interface
  • 89. Howto: undo a commit● Commit the inverted patch of a previous commit● hg backout <rev>
  • 90. Quiz 4● What is the command to discard changes?
  • 91. Quiz 4● What is the command to discard changes? ○ hg revert
  • 92. Quiz 4● What is the command to discard changes? ○ hg revert● What protocols can be used for push/pull?
  • 93. Quiz 4● What is the command to discard changes? ○ hg revert● What protocols can be used for push/pull? ○ SSH and HTTP
  • 94. Quiz 4● What is the command to discard changes? ○ hg revert● What protocols can be used for push/pull? ○ SSH and HTTP● Which head should you merge to?
  • 95. Quiz 4● What is the command to discard changes? ○ hg revert● What protocols can be used for push/pull? ○ SSH and HTTP● Which head should you merge to? ○ The one with the most changes
  • 96. End of the basics.● But theres much, much more. ○ Advanced commands (cat, archive, locate, grep) ○ revsets ○ mq ○ (let me know what you would like to know) ○ Anyone interested?● Links: ○ http://confluence.incubaid. com/display/ENG/Incubaid+Starter+Kit ○ http://confluence.incubaid. com/display/ENG/Mercurial+Cheat+Sheet+- +Hg+Cheat+Sheet ○ http://hginit.com/ ○ http://hgbook.red-bean.com/
  • 97. Thank you!● Questions?
  • 98. Advanced● hg cat ● hg recover● hg archive ● hg resolve ?● hg bisect ● hg revert● hg copy ? ● hg rollback● hg grep ● ext: record● hg locate