GitHub Notes by follower

Notes about using GitHub (mostly with Mercurial via hg-git plugin)

Using Mercurial with GitHub

  • Install hg-git plug-in for Mercurial.

Steps to start a new Mercurial project on GitHub

  • Make new repository repo-name on GitHub. (All this via.)

  • Locally:

        mkdir <repo-name>
        cd <repo-name>
        hg init .
    
  • Create .hg/hgrc and add:

        [ui]
        username = name <email>
    
        [paths]
        default = git+ssh://git@github.com/<user>/<path/to/repo>.git
    
  • Locally:

        touch README.txt
        hg add README.txt
    
        hg ci -m "Initial check-in."
    
        hg bookmark -r default master
    
        hg push git+ssh://git@github.com/<user>/<path/to/repo>.git
    

Creating git branches on GitHub with Mercurial

It appears that branches created with the Mercurial branch command are not converted to git branches as displayed by GitHub. Instead the branch information is stored in the commit message.

I wanted to create branches that are accessible via the "Branches" menu in the GitHub UI.

In order to this you need to use the Mercurial bookmarks command instead.

Example (from existing fresh repository) (for result see):

  1. Clone the existing repository locally:

    hg clone git+ssh://git@github.com:follower/test-hg-git-2.git
    
  2. Add self to .hg/hgrc as above.

  3. Create, add and commit a README file.

  4. Push the commit with:

        $ hg push
    

    This should result in:

        importing Hg objects into Git
        creating and sending data
            default::refs/heads/master => GIT:2abdce11
    
  5. The following should show the current status:

        $ hg tags
    
        tip                                0:17bacae247a7
        master                             0:17bacae247a7
        default/master                     0:17bacae247a7
    
        $ hg bookmarks
    
         * master                    0:17bacae247a7
    

    The * indicates the active branch.

  6. To create a new branch you need to add a bookmark:

       $ hg bookmark new-branch
    
  7. Now the current status should be:

        $ hg tags
    
        tip                                0:17bacae247a7
        new-branch                         0:17bacae247a7
        master                             0:17bacae247a7
        default/master                     0:17bacae247a7
    
        $ hg bookmarks
    
         * new-branch                0:17bacae247a7
         * master                    0:17bacae247a7
    

    (But note nothing new has been pushed to the git repo yet.)

  8. Now we push to the remote repo:

        $ hg push
    
        pushing to git+ssh://git@github.com:follower/test-hg-git-2.git
        importing Hg objects into Git
        creating and sending data
            default::refs/heads/master => GIT:2abdce11
            default::refs/heads/new-branch => GIT:2abdce11
    

    (Note however that this has not created a new branch at the remote repository.)

  9. The current status should be:

        $ hg tags
    
        tip                                0:17bacae247a7
        new-branch                         0:17bacae247a7
        master                             0:17bacae247a7
        default/new-branch                 0:17bacae247a7
        default/master                     0:17bacae247a7
    
        $ hg bookmarks
    
         * new-branch                0:17bacae247a7
         * master                    0:17bacae247a7
    

    (Note that a default/new-branch tag has been added.)

  10. Add a new line to the README and commit the change (this will be the first change in the new branch).

  11. Current status:

        $ hg bookmarks
    
         * new-branch                1:cf1b7955598a
         * master                    1:cf1b7955598a
    
        $ hg tags
    
        tip                                1:cf1b7955598a
        new-branch                         1:cf1b7955598a
        master                             1:cf1b7955598a
        default/new-branch                 0:17bacae247a7
        default/master                     0:17bacae247a7
    

    (Note that both new-branch and master currently point to the latest revision--we need to change this.)

  12. We need to force the master branch to return to the previous state (i.e. revision 0) (Note: This needs to happen before we push to the remote repo):

        hg bookmark -f -r 0 master
    

    (Note: I'm not sure if there's a better way to achieve this.)

  13. Current status:

        $ hg bookmarks
    
         * new-branch                1:cf1b7955598a
           master                    0:17bacae247a7
    
        $ hg tags
    
        tip                                1:cf1b7955598a
        new-branch                         1:cf1b7955598a
        master                             0:17bacae247a7
        default/new-branch                 0:17bacae247a7
        default/master                     0:17bacae247a7
    

    (Note that only the new-branch is marked as active & the revision has changed.)

  14. Now we push this change to the remote repository which should now have the new branch visible:

        $ hg push
    
        pushing to git+ssh://git@github.com:follower/test-hg-git-2.git
        importing Hg objects into Git
        creating and sending data
            default::refs/heads/master => GIT:2abdce11
            default::refs/heads/new-branch => GIT:094384da
    

    (Note that you'll get an error here if you earlier pushed before changing the revision to which master pointed.)

  15. The new branch should now be visible under the "Branches" menu in the GitHub UI.

  16. Current status:

        $ hg bookmarks
    
         * new-branch                1:cf1b7955598a
           master                    0:17bacae247a7
    
        $ hg tags
    
        tip                                1:cf1b7955598a
        new-branch                         1:cf1b7955598a
        default/new-branch                 1:cf1b7955598a
        master                             0:17bacae247a7
        default/master                     0:17bacae247a7
    
  17. Now we can change between branches with:

        $ hg update <branch-name>
    

    For example:

        $ cat README
    
        A demo of branches with `hg-git`.
        This branch has had line added.
    
        $ hg update master
    
        1 files updated, 0 files merged, 0 files removed, 0 files unresolved
    
        $ hg bookmarks
    
           new-branch                1:cf1b7955598a
         * master                    0:17bacae247a7
    
        $ hg tags
    
        tip                                1:cf1b7955598a
        new-branch                         1:cf1b7955598a
        default/new-branch                 1:cf1b7955598a
        master                             0:17bacae247a7
        default/master                     0:17bacae247a7
    
        $ cat README
    
        A demo of branches with `hg-git`.
    
  18. Then we can make an edit just in the master branch:

        # Edit README then...
    
        $ hg ci -m "Add line in master." README
    
        created new head
    
        $ hg bookmarks
    
           new-branch                1:cf1b7955598a
         * master                    2:09e107683382
    
        $ hg push
    
        pushing to git+ssh://git@github.com:follower/test-hg-git-2.git
        importing Hg objects into Git
        creating and sending data
            default::refs/heads/master => GIT:4c75ca67
            default::refs/heads/new-branch => GIT:094384da
    
  19. And an edit just in the new-branch branch:

        $ hg update new-branch
    
        1 files updated, 0 files merged, 0 files removed, 0 files unresolved
    
        $ hg bookmarks
    
         * new-branch                1:cf1b7955598a
           master                    2:09e107683382
    
        $ hg tags
    
        tip                                2:09e107683382
        master                             2:09e107683382
        default/master                     2:09e107683382
        new-branch                         1:cf1b7955598a
        default/new-branch                 1:cf1b7955598a
    
        # Edit README then...
    
        $ hg ci -m "Added another line to just this branch."
    
        $ hg bookmarks
    
         * new-branch                3:98225c718bb4
           master                    2:09e107683382
    
        $ hg tags
    
        tip                                3:98225c718bb4
        new-branch                         3:98225c718bb4
        master                             2:09e107683382
        default/master                     2:09e107683382
        default/new-branch                 1:cf1b7955598a
    
        $ hg push
    
        pushing to git+ssh://git@github.com:follower/test-hg-git-2.git
        importing Hg objects into Git
        creating and sending data
            default::refs/heads/master => GIT:4c75ca67
            default::refs/heads/new-branch => GIT:d0c65ce5
    

TODO: Add merge example.

Mercurial/hg-git branch/bookmark related links