Table of Contents

Overview of Repositories

Repositories is where your source code lives and prospers. They can be browsed via the web interface or can be interacted with using any of the Mercurial client tools, including hg.exe itself, as well as any of the GUI clients.

Adding Repositories

To add a Repository to the Project, you need to have a "Repository Management" permission (or be a System Administrator). Click the "+ Repository" button on the Repositories page and you'll see a dialog:

Name

The name of the Repository. Choose wisely, as changing the name will also change the URL for cloning, pulling and pushing

Description

A few words on what the repository is all about.

.hgignore File

HgLab can initialize a newly created repository with a .hgignore file (courtesy of github/gitignore).

Largefiles Extension

Makes this repository Largefiles-enabled. Note that when you enable this feature for the repository in HgLab, clients will also need Largefiles extension to be enabled.

Importing Existing Repositories

If you already have Mercurial repositories you want to import into HgLab, follow these simple steps:

1. Add a Repository as shown above, but do not initialize it with a .hgignore file; leave this dropdown empty
2. Push the existing repository to HgLab using whatever client you prefer

Cloning, Pulling and Pushing

Cloning Repositories from HgLab

In order to start collaborating on code, you first need to grab yourself a copy of the repository. In a DVCS world, this is called cloning.

To find out where to clone from, click on the blue Clone button on any of the Repository pages:

Copy the hg clone ... command and paste it into your terminal of choice. Alternatively, you can click on the "Cloning Instructions" link and see more information on cloning and configuring Mercurial.

Cloning Using SourceTree

Open up the "Clone / Add / Create Repository" dialog by clicking on the "Clone / New" icon in the main SourceTree application toolbar. Paste the clone URL into the "Source Path / URL" input:

Cloning Using TortoiseHg

Open up "Clone" dialog by clicking "Clone Repository..." in "File" menu in TortoiseHg Workbench. Paste the clone URL into the "Source" input:

Pulling from HgLab

Just as with clones, you can freely pull from the Repository that is publicly accessible. Pull URL is identical to Clone URL.

Pushing to HgLab

In order to push your changes, you must have a write access to the Repository you're pushing to. This means that you have to have an account within HgLab and be a Team Member of the Project.

Push URL is identical to Pull and Clone URLs.

Browsing Repositories

HgLab offers a full-featured web interface for browsing repositories, including exploring directories and files, browsing branches, bookmarks and tags.

HgFlow Support

If the repository has HgFlow enabled, "Branches" tab is replaced with a more specialized "Flow" tab, which details all the development streams and provides more advanced comparison logic.

Browsing Branches

"Branches" tab shows a list of all active branches in the repository (append ?closed=true to the URL to see all branches ever created).

Of particular interest here is the branch divergence information. "Ahead" (green number with the leading "+") is the number of commits on some particular branch that do not exist on the Mainline Branch, whereas "Behind" (red number with the leading "-") is very much the opposite: the number of commits on the Mainline Branch that do not exist on this branch.

"Ahead" and "Behind" are almost like a kind of "age" metric. The "Ahead" number tells you roughly how much impact the branch will have on the Mainline Branch should it be merged. The "Behind" number tells you how much work has happened on the Mainline Branch since this branch was started.

To see exatly what has changed, click on the button on the right of the row to see the Compare view.

Multiple Heads Warning

If you happen to have multiple heads on any of your branches, HgLab will warn you about that by displaying a yellow alert on the Source tab:

Discussing Commits

HgLab facilitates commit discussions by having commit-level and diff-level comments. Commit-level comments are available to any authenticated Team member and can be accessed by scrolling to the bottom of the commit page.

Diff-level comments can be added by hovering over the line in question and clicking on the blue "+" icon on the left:

The eye icon toggles between authoring and preview modes. Comments support Markdown, Emojis and @mentions.

Approving Commits

HgLab has a light-weight approval process that allows teammates to Approve a commit, essentially green-lighting changes.

Later, when browsing commits, HgLab displays the total number approvals for a particular commit as either a gray or a green circle. Gray badge shows how many reviewers have approved a particular change. The badge turns green for the commits that were reviewed and approved by you.

Comparing

Every repository contains a Compare view, which allows you to compare the state of your repository across branches, tags, commits and more.

The Compare page brings all information needed to determine what changed over a series of commits onto a single page: a list of commits in chronological order and a rollup diff of all changes between the two points. All in the same place and with a single well-defined URL.

The Compare page features two textboxes where you need to enter changeset identifiers. The leftmost input should be considered the starting point of your comparison, and the rightmost one is the endpoint.

You can compare branches and tags by typing names into the respective inputs.

Starring

When you Star a Repository, it gets included into a Starred tab on the Dashboard and gets included into a Starred Repositories list:

Activity from Starred Repositories will not appear in Activity Feed in the Dashboard, nor will you receive email notifications.

Downloading Source Code

Clicking on the button shown above allows you to download a plain old ZIP file with all the source code for a particular changeset, branch or tag.

Settings

Repository Settings page is accessed by clicking on the wrench icon in the tabbar:

General

Repository Description

Short summary on what this entire Repository is about. Use Emoji and Markdown for an extra bit of coolness.

Mainline Branch

Adjust the Mainline Branch in case your workflow requires development to happen on a branch other than standard default. This will only affect how HgLab presents various bits of information in the web UI and will introduce special Virtual @ Bookmark.

Here Be Dragons

This is where you can delete repository from HgLab.

Actual Mercurial repository will not be deleted.

Hooks

Every Repository in HgLab has the option to communicate with a web server whenever the Repository is pushed to. These "hooks" can be used to update an external issue tracker, trigger CI builds, update a backup mirror, or even deploy to your production server.

When a Repository is pushed to, HgLab issues an HTTP POST request to the provided URL with the following payload and headers.

Payload

{
  "repository": {
    "name": "hgsharp",
    "project": {
      "name": "HgSharp",
      "slug": "hgsharp",
      "project_lead": {
        "email_address": "anton.gogolev@hglabhq.com",
        "full_name": "Anton Gogolev"
      }
    }
  },
  "pushed_by": {
    "email_address": "anton.gogolev@hglabhq.com",
    "full_name": "Anton Gogolev"
  },
  "pushed_at": "2014-08-06T14:00:41.0675Z",
  "commits": [
    {
      "node_id": "f294fa157a3da934a4d57ea7a971693485e8fcd6",
      "committed_by": {
        "email_address": "anton.gogolev@hglabhq.com",
        "full_name": "Anton Gogolev"
      },
      "committed_at": "2014-07-23T11:29:39+04:00",
      "comment": "`HgManifestWriter`: Sort entries before writing them",
      "branch": {
        "name": "default",
        "closed": false
      },
      "files": [
        "src\/HgSharp.Core\/HgManifestWriter.cs"
      ]
    },
    {
      "node_id": "3cc48c200229270220ffd0f911631bb0a2819068",
      "committed_by": {
        "email_address": "anton.gogolev@hglabhq.com",
        "full_name": "Anton Gogolev"
      },
      "committed_at": "2014-07-23T11:29:57+04:00",
      "comment": "`HgRepository`: Minor changes in `Commit()`",
      "branch": {
        "name": "default",
        "closed": false
      },
      "files": [
        "src\/HgSharp.Core\/HgRepository.cs"
      ]
    }
  ]
}

Headers

X-HgLab-Signature

This header is only included if you set the "Secret Key" when adding a Hook. It contains the HMAC-SHA256 of the Payload.

Configuring Access Control

HgLab supports all the features Acl Extension: branch- and path-level permissions, users and groups.

In order to configure ACLs, open up hgrc (note that there's no dot in the file name) for the appropriate repository on the server and add the following lines:

[acl]
# This setting is required for HgLab to start respecting ACL settings
sources = serve

All the usual sections ([acl.deny.branches], [acl.allow.branches], [acl.deny], [acl.allow]) apply, with one minor change: where original Acl Extension expects Groups, HgLab uses Roles. This is done to better integrate with Teams.

For example, if you have a "Core Developers" team which has "Developers" and "Release Engineers" roles assigned to it, here's how you can deny pushes to production branch to anyone who does not have a "Release Engineers" role:

[acl.allow.branches]
production = @release-engineers