Your SlideShare is downloading. ×
Mercurial Tutorial
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×

Saving this for later?

Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime - even offline.

Text the download link to your phone

Standard text messaging rates apply

Mercurial Tutorial

616
views

Published on

A near exhaustive

A near exhaustive

Published in: Technology

0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
616
On Slideshare
0
From Embeds
0
Number of Embeds
5
Actions
Shares
0
Downloads
21
Comments
0
Likes
1
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. HgTutor All Lessons
  • 2. Short Tutorials Setting up 1 minute, Only once in your life
  • 3. Setting upDo this before everythingEdit the file ~/.hgrc (if it doesnt exist, create it)Put these in:[ui]username= Your Name <your_email_adress.>[extensions]hgext.convert=hgext.fetch={other extension stuff you want to enable}Save it.
  • 4. A config all to myself•  Just like vi or emacs or bash, mercurial has a configuration file in your home directory•  You can edit this file at ~/.hgrc•  You will need to set your username and e-mail in it (Mercurial won’t work without it)•  You can also enable new extensions in this file, such as hg fetch or hg convert
  • 5. Only once in your life
  • 6. Only once in your life
  • 7. Only once in your life
  • 8. Only once in your life
  • 9. Only once in your life
  • 10. Short Tutorials Starting a new project locally just for you in your home dir.
  • 11. Starting a new project locallyIn short:Wherever you want a new repo, dohg init path/to/new/repoOr to convert a regular directory into a hg repository:cd path/to/that/directoryhg init
  • 12. Starting a new project locally•  For you only, in your home directory:
  • 13. Starting a new project locally•  Creating a new repo: Easy as pie In this slide cd Projects hg init My_New_Project
  • 14. Example Starting a new project locally situation /home/staff/irmak/ Projects/My_New_Project/Source: http://www.hginit.com
  • 15. Short Tutorials Simple local workflowWhat you will do most with your own Mercurial repo
  • 16. Simple local workflowIn short:Make your changes.hg status to see what files are different from last versionhg add to add all new files to the repo hg commit -m “message” to commit changes without opening an editorhg log to see history of changes (all versions)
  • 17. Simple local workflowMore commands:Make your changes.hg status to see what files are different from last versionhg diff to see specifically what changes in each filehg add to add all new files to the repo hg add filename to just add specific fileshg remove filename to delete files (locally AND from repo)hg forget filename to stop tracking changes on a filehg addremove to add files, forget files you deleted, make everything sane.hg commit to commit changes (opens an editor for a summary of changes)hg commit -m “message” to commit changes without opening an editorhg log to see history of changes (all versions)hg update number to go back to that versionhg update to go to latest versionhg revert to go back to previous version
  • 18. Simple local workflow•  Remember this?
  • 19. Simple local workflow•  Say we created two files In this slide cd My_New_Project ls emacs new_file1 emacs new_file2 ls
  • 20. Simple local workflow•  Add the files to the repo, and commit the changes In this slide hg stat hg add hg commit -m “Testing”
  • 21. Simple local workflow•  Say we now changed something in a file In this slide emacs new_file1 hg stat
  • 22. Simple workflow•  Commit the changes In this slide hg commit -m “Changed some wording”
  • 23. Simple local workflow•  Log shows the history of your changes In this slide hg log
  • 24. Short Tutorials Starting a new lab project A central repo in /home/projects for a lab project
  • 25. Starting a new lab projectIn short:Go to wherever the repo will be in /home/projectshg init /home/projects/path/to/central/repoIf you need other people to contribute to it,do the necessary permission changes, i.e.chmod g+w /home/projects/path/to/central/repo
  • 26. Starting a new lab project•  Lets say we want to create a repo in /home/projects/Social•  which can be accessed by any member of the social group.
  • 27. Starting a new lab project•  Oh my god its so EASY•  Youre done if you dont need members of social to contribute In this slide cd /home/projects/Social hg init Super_New_Project
  • 28. Starting a new lab project•  Check the permissions: user irmak has read/write group social has only read permissions In this slide ls -ld Super_New_Project
  • 29. Starting a new lab project•  Easily remedied: Give the group write permissions•  Thats IT! In this slide chmod g+w Super_New_Project ls -ld Super_New_Project
  • 30. Current Starting a new lab project situation /home/projects/Social/ Super_New_Project/Source: http://www.hginit.com
  • 31. Short Tutorials Checking out a lab project you want your own working copy from a central repo
  • 32. Checking out a lab projectIn short:Go to wherever you want to have your local repo / working copy (those two arethe same thing in Mercurial)hg clone /home/projects/path/to/central/repoor if you want the local repo to be named differently,hg clone /home/projects/path/to/central/repo path/to/new/local/repoIf you are not inside the filesystem (i.e. if you work from home)hg clone ssh://barcelona//home/projects/path/to/central/repoorhg clone ssh://irmak@barcelona.chem-eng.northwestern.edu//home/projects/path/to/central/repoYou can switch “barcelona” with any workstation name.
  • 33. Checking out a lab project•  Remember this?•  Lets check out a local repo clone of this central repo.
  • 34. Checking out a lab project•  Lets go to our home dir. In this slide cd ~
  • 35. Checking out a lab project•  Clone the repo.•  Thats it. You have your own copy. In this slide cd Projects hg clone /home/projects/Social/Super_New_Project/
  • 36. Checking out a lab project•  As you can see, its empty.•  Nobody committed/pushed any changes yet: no log (no history) In this slide ls -ld Super_New_Project/ cd Super_New_Project ls hg log
  • 37. Current Checking out a lab project situation /home/projects/Social/ Super_New_Project/ /home/staff/irmak/ Projects/Super_New_Project/Source: http://www.hginit.com
  • 38. Short Tutorials Workflow with a central repo What you will do most if you have a central repo like a shared lab project
  • 39. Workflow with a central repoIn short:Same as Simple Local Workflow,hg commit to keep committing changes locallyWhen you have a good next version:(hg outgoing shows what changes you will share with the central repo)hg push to push to share changes with the central repoIf others changed the same files, youll get a warning, pull and merge their changes before pushing yours (see below for pull & merge)To get the changes from other people:(hg incoming shows what changes you will get from the central repo)hg pull to pull others changes from the central repohg merge to combine your changes with theirs (automatic, painless)hg update to switch to working on this latest version you got
  • 40. Short Tutorials Workflow with a central repo a. Everyday changes in local repo What you do between having definitive versions (Same as simple local workflow between pushes/pulls)
  • 41. Current Workflow with a central repo situation /home/projects/Social/ Super_New_Project/ /home/staff/irmak/ Projects/Super_New_Project/Source: http://www.hginit.com
  • 42. Everyday changes inWorkflow with a central repo local •  Go to your local repo On this personal repo, you follow the same Simple Local Workflow. You commit your changes, it keeps track. Central repo doesnt know that yet.
  • 43. Everyday changes inWorkflow with a central repo local •  Its empty. Lets change that. In this slide cd Projects/Super_New_Project
  • 44. Everyday changes inWorkflow with a central repo local •  Now there is a file in there. In this slide emacs new_stuff.txt cat new_stuff.txt
  • 45. Everyday changes inWorkflow with a central repo local •  Add & commit. This commit is still to your local repo. In this slide hg stat hg add hg commit -m “Plans about Project” hg log
  • 46. Everyday changes inWorkflow with a central repo local •  Change even more: The project progresses. In this slide emacs new_stuff.txt cat new_stuff.txt
  • 47. Everyday changes inWorkflow with a central repo local •  Now we have OUR latest version.•  Lets push all these changes to the central repo. In this slide hg stat hg commit -m “Additional plans” hg log
  • 48. Pushing a new versionWorkflow with a central repo to central •  hg outgoing shows the changes we will be pushing.•  In this case, itll push both changesets (central doesnt have them) In this slide hg outgoing
  • 49. Pushing a new versionWorkflow with a central repo to central •  (We didnt need the hg outgoing step. That was just to check)•  Ok, now do it. Push. The changes are now also in the central repo. In this slide hg push
  • 50. Short Tutorials Workflow with a central repo b. Working with multiple local repos When you want to work on your project from home or vacation, and keep everything synched.
  • 51. Current Workflow with a central repo situation /home/projects/Social/ Super_New_Project/ /home/staff/irmak/ Projects/Super_New_Project/Source: http://www.hginit.com
  • 52. Working with multipleWorkflow with a central repo local repos •  You go home. You want to work from home.•  Need another local clone of the central repo at home.
  • 53. Working with multipleWorkflow with a central repo local repos •  Imagine tunis is my home computer now please.•  This is what Id do on my home laptop. Careful with the double // In this slide hg clone ssh://irmak@istanbul.chem-eng.northwestern.edu//home/projects/Social/Super_New_Project/ ls
  • 54. Working with multipleWorkflow with a central repo local repos •  I just received the latest version.•  The central had all the changes. In this slide cd Super_New_Project/ ls cat new_stuff.txt
  • 55. Working with multipleWorkflow with a central repo local repos •  hg log shows all the history.•  You could go to any older version if you wanted. In this slide hg log
  • 56. Current Workflow with a central repo situation /home/projects/Social/ Super_New_Project/ /home/staff/irmak/ Projects/Super_New_Project/ In home laptop: ~/ Super_New_Project/Source: http://www.hginit.com
  • 57. Working with multipleWorkflow with a central repo local repos •  Working at home, you make progress.•  You keep committing your changes (locally) In this slide emacs new_stuff.txt hg stat hg commit -m Fixed grammar, added more stuff mv ../some_code.py . emacs other_code.py hg stat hg add hg commit -m Started coding
  • 58. Working with multipleWorkflow with a central repo local repos •  Youre done. Push these to central,•  so you can get them when youre at work tomorrow. In this slide hg push
  • 59. Working with multipleWorkflow with a central repo local repos •  At work, you can pull all those changes and continue working.•  Check what youll be pulling with hg incoming (Even if you forget to pull and make other changes on the repo at work, no problem. You can pull & merge later.) In this slide cd Projects/ cd Super_New_Project/ hg incoming
  • 60. Working with multipleWorkflow with a central repo local repos •  Do it, pull the changes you made at home.•  This gets all the changes, but does not apply them yet. In this slide hg pull
  • 61. Working with multipleWorkflow with a central repo local repos •  hg log shows you the complete history you have now.•  You see that you have the changes. BUT -- In this slide hg log
  • 62. Working with multipleWorkflow with a central repo local repos •  hg summary tells you that on that history, this copy is at version 1.•  (parent is where youre at now) In this slide hg summary
  • 63. Working with multipleWorkflow with a central repo local repos •  So you know about the latest version, youre not working with it yet.•  hg update to switch to the latest version (3) In this slide hg update
  • 64. Short Tutorials Workflow with a central repo c. Team Work Working on the same project with multiple people Changing different parts at the same time Sharing these changes
  • 65. Working with multipleWorkflow with a central repo local repos •  During these pushes and pulls, we didnt need to merge.•  Mergings needed if the same file is changed by different local repos,at the same time, without central knowing about it yet.•  Like when people are working on different parts of the same paper, for example.•  Hg will warn you about that, if you try to push a file that was changed by someone else.•  Then all youll do is hg pull their changes, hg merge to combine your changes with theirs, and then you can hg push normally.•  Read http://hginit.com/02.html for a good and well explained example of a team working on a repository together, including merges.
  • 66. Workflow with a central repo Team work •  If Andriana cloned her own in /home/projects local repo from the central, we would have this picture •  For each local repo, follow Simple local workflow in my in Andrianas in my home personal home dir. dir. •  For sharing changes laptop between people / computers, follow Workflow with a central repoSource: http://www.hginit.com
  • 67. Short Tutorials Converting an svn repo to hg Dont panic. Extremely simple.
  • 68. Converting an svn repo to hgIn short:To create a separate Mercurial repo from an svn repo hg convert /path/to/svn/repoThats it.Your svn repo will be left unchanged.A new hg repo will emerge.(and it will know everything that svn knew)If the svn repo was called “ProjectName”, the new hg repo will be a new directory called“ProjectName-hg” (you can specify a different name if you want)
  • 69. Converting an svn repo to hgIn short:To create a separate Mercurial repo from an svn repo hg convert /path/to/svn/repoYou can do this:- to a local svn working copy- to the actual place where the svn repository residesEither way works.There are no real differences between resulting hg repos.Choose the more convenient one according to your needs.
  • 70. Converting an svn repo to hgIn short:Converting your svn working copy:hg convert ~/Projects/CommunitiesSA Youll get a repo right there, youll probably use that locally(Simple local workflow)Converting the actual svn repository:hg convert /home/projects/Networks/CommunitiesSAThats probably what youll do with lab projects to get a central hg repo, then youllclone local hg repos to your home dir., other places, other peoples homes, etc.(wherever needed)(Workflow with a central repo)
  • 71. Converting an svn working copy Example workflow to get an hg repo (for local use purposes) from an svn working copyExample svn working copy:/home/visitors/adampah/Projects/Hadoop-hCluster
  • 72. Converting an svn working copy •  Lets convert a working copy. •  Go to where your working copies of svn repos are. •  Hmm. I say we convert this Hadoop-hCluster In this slide cd Projects ls -l
  • 73. Converting an svn working copy •  Apply the convert command. •  You can see it processing every version in the svn repo •  This creates Hadoop-hCluster-hg here. •  Its an hg repo with all the files and version history of Hadoop-hCluster In this slide hg convert Hadoop-hCluster
  • 74. Converting an svn working copy •  You can check if you really have all the version history with an hg log •  Its all there! •  The changes are all there, but dont forget hg update to apply them and switch to the latest version. In this slide cd Hadoop-hCluster-hg hg log
  • 75. Current Converting an svn working copy situation /home/visitors/adampah/ Projects/Hadoop-hCluster-hgSource: http://www.hginit.com
  • 76. Converting a shared lab svn repo Example workflow to get a central hg repo setup from an svn repoExample svn repository:file:///home/projects/Systems-Biology/Worm-Egg-Laying/
  • 77. Converting a shared lab svn repoGo to the parent directory of svn repo.cd /home/projects/Systems-Biology/Convert the repo.hg convert Worm-Egg-LayingCheck permissions.ls -ld Worm-Egg-LayingGive necessary permissions.chmod g+w Worm-Egg-LayingCentral repo ready. Go home to get a local repo there.cd ~Go to where you want to have your local repo.cd ProjectsClone the central repo.hg clone /home/projects/Systems-Biology/Worm-Egg-Laying-hg
  • 78. Current Converting a shared lab svn repo situation /home/projects/Systems-Biology /Worm-Egg-Laying-hg /home/staff/irmak/ Projects/Worm-Egg-Laying-hgSource: http://www.hginit.com
  • 79. Converting an svn repo to hgFinal Notes:If you convert an svn repository with a trunk/tags/branches structure,hg convert will automatically handle all of it –if you were only using trunk, your hg repo will have what trunk had.hg convert gets all the versions, but doesnt apply them to the new directory.You should do hg update to switch to the last version if you want to work in it.But if you will hg clone another repo from this (i.e. to get your own local repo), thats fine.The cloning will update your new clone automatically.
  • 80. Short Tutorials Working together with svn repositories Mercurial understands svn
  • 81. Working on top of an SVN repository•  What if you have to have an SVN repository that you are actively working on?•  There is an extension that can help you work with this, it is called hg-subversion•  This extension allows you to work in Mercurial commands, that are then translated to SVN commands•  To check out a project nose to use with hg subversion you would do:•  After that you can work as normal•  A word of warning though, this is still an extremely active coding project and it may change or break at any time.•  Don’t rely on this to work with all of your repos!
  • 82. Just accepting that it’s SVN•  There are some projects where neither of those things make sense, such as •  Ones that have to stay as SVN for legacy reasons •  But aren’t actively used enough to do anything special for •  Like JabRef•  Fortunately Mercurial supports subrepositories•  These subrepositories can be Mercurial repos or SVN repos
  • 83. Just accepting that it’s SVN•  First, you must create the main repository and the ‘nested’ repository
  • 84. Just accepting that it’s SVN•  Next, tell it where the path is and put it into the .hgsub file•  Now you can just continue to use svn commands with this subrepo•  Or you can use hg-subversion with it•  It’s up to you!
  • 85. Short Tutorials Advanced Topic: Version control on large files
  • 86. An introduction to Mercurial and big files•  So first, let’s clear up what are big files.•  Mercurial by default warns you about any file over 10 MB.•  You might worry about this but don’t! It works with that file anyway•  It warns you because extremely large files cause a clone over the internet to go really slow (of course, there’s no way around this. 1 GB is 1GB no matter what)•  Mercurial is designed for this decentralized type of collaboration so it warns you to make you think whether you really need that file in there or not•  Sometimes you do need that file and sometimes you don’t, so let’s evaluate these situations
  • 87. I don’t need that big stinking file!•  Our filesystem is (or should) be backed up•  So if you have a large file (hundreds of megabytes) that is not going through versions i.e. it just sits there it doesn’t necessarily need to be in version control•  This is especially true when you don’t actually share your repository with anyone.•  There is a simple way you can do this, you can create a .hgignore file•  This file tells Mercurial what to ignore
  • 88. Creating a .hgignore•  First, create the file
  • 89. Creating a .hgignore•  Next, set it up and then tell it what to ignore•  It can be specific file names or regular expressions, but be careful with regexes!
  • 90. Creating a .hgignore•  Then just add and commit the .hgignore file
  • 91. Creating a .hgignore•  Then just add and commit the .hgignore file
  • 92. Okay, I actually need these large files•  So these files are large and constantly changing, I need to keep track of them•  You could continue to have Mercurial track them, but it’s not the best solution•  There are multiple extensions that have been created to solve this problem•  You can choose from Big Files, bFiles, or Snap•  Snap is what has been chosen as the lab standard, it’s the simplest/most self contained•  You can pick whichever one you want though and pursue it•  All of these are under heavy development and are constantly changing•  However, they all have the same basic idea
  • 93. How do these extensions actually work?•  The way that these extensions work is fairly simple•  What they do is for any file above a given size, they take it out of Mercurial’s control and put it into theirs•  So when these files are committed or changed what they do is make a tar file of that file and commit it to its own repository•  This zipped file has a MD5 hash that is used as an identifier•  A string that incorporates the file name and the MD5 hash is then placed in a file that Mercurial keeps track of•  This way Mercurial versions just the strings itself, which are fairly small
  • 94. How do these extensions actually work?•  When the file changes, instead of keeping diffs of it (which would be really large) it just creates a new zip of the file with a new MD5 sum•  You can still diff between the different versions of the file but the extension handles the diff’ing
  • 95. Checking out Snap•  To actually use this the first thing you have to do is check out Snap, it is hosted on the internet
  • 96. Checking out Snap•  To actually use this the first thing you have to do is check out Snap, it is hosted on the internet
  • 97. Setting up Snap•  Next you have to determine if you want snap to be global or project specific•  If it is global then you need to configure your .hgrc•  If it is project specific then you should modify the .hgrc file in the .hg directory of the project•  Your .hgrc file should now look something like this:
  • 98. Setting up Snap•  The ‘hgext.snap’ line tells Mercurial where snap is and activates the extension•  The ‘[snap]’ section configures special things about snap and is not necessary•  ‘size_threshold’ tells it the file size at which it should start working, mine is set for 750 MB•  ‘patterns’ tells it what regex patterns it should act on regardless of the file size•  If these two aren’t configured then it will work on any file over 10 MB by default
  • 99. Using Snap•  Once you have Snap set up it will automagically work•  You can tell that it is working because after a ‘hg add’ and ‘hg commit’ it will tell you how many files were added to a repository and of those how many were snap files•  A fair warning though, this will slow down mercurial•  This is because it is tracking all those files for changes and checking MD5 sums•  It is faster than just having Mercurial do it, but you will still suffer a slowdown
  • 100. Short Tutorials Resources Where to look to get quick help and to learn more
  • 101. Resources•  http://hginit.com/•  Good explanation of concepts•  Great examples for almost anything youll need to do•  Pictures, screenshots, diagrams: very clear•  Easy to read, humorous, not too long•  Very helpful resource, highly recommended to read once•  http://mercurial.selenic.com/guide•  Official guide•  Very short, to the point, like a collection of cheatsheets•  Organized in workflows•  What you need to do in which order for every use case•  Not for digesting the concepts•  Ideal for quickly checking how to do something