Documentation for Kiln
Documentation for Kiln
Licensed Version: 2.9.60
Hosted Version: 2.9.52
Generated on 2013-01-10
Email: customer-service@fogcreek.com
Toll Free: 1-866-FOG-CREEK
Outside North America: +1 (212) 279-2076
Table Of Contents
1
2
What are the system requirements for Kiln?
Kiln currently supports:
Windows 2003 Server SP2 or later, Windows 2008 Server, and Windows 2008 Server R2 (sorry; Itanium not supported)
Microsoft SQL Server (2005, 2008, 2008 Express, or 2012)
Full-Text Search is required for Kiln 2.8 and earlier.
Note that the Express edition has a 10 gig database size limit and 1 gig RAM limit
Microsoft IIS 6.0 and later
2 GB RAM Minimum; 8 GB RAM Recommended
Running Kiln or the FogBugz/Kiln bundle in a virtual machine is not generally recommended. Since Kiln is an extremely disk-heavy application, you may experience performance degradation. Please see Can I run Kiln in a VM / Virtual Machine?
if you are considering running Kiln in a virtual environment.
The KilnRepositories folder requires a physical disk ( not a network share )
On the client side, please make sure you're using one of our supported browsers .
Note that Kiln cannot currently be installed on a Primary Domain Controller. Also note that Kiln
must
be installed on the same server as
FogBugz.
See also this posting on the FogBugz Knowledge Exchange
Was this article helpful?: Yes No
3
How do I install Kiln 2.x?
Overview
Every licensed Kiln customer can download an installer which has a wizard to help guide you through the various steps needed to get Kiln running on your server. For the vast majority of customers,
the defaults we've selected will be your best bet
for a successful installation.
This document has a few sections:
1. System Requirements
2. Before you begin
3. Installer Walk-through
4. Advanced Instructions
1. System Requirements
Kiln supports a narrow range of systems at the moment. Make sure you're installing on a system that meets these requirements because we can't support anything else right now (sorry!).
Operating System(s)
Windows 2003 and 2008 server
Database Server(s)
Microsoft SQL Server 2005, 2008, 2008 Express*, or 2012. (Full Text Search is required for Kiln 2.8 and earlier.)
* Note that the Express edition has a 10 gig database size limit and 1 gig RAM limit
Physical vs. Virtual Machine
Running Kiln or the FogBugz/Kiln bundle in a virtual machine is not generally recommended. Since Kiln is an extremely disk-heavy application, you may experience performance degradation. Please see Can I run Kiln in a VM / Virtual Machine?
if you are considering running Kiln in a virtual environment.
2. Before You Begin
Just a few things that we wanted to let you know before you begin the installation process:
1.
The server may require a restart to finish.
If it does, just restart the installer and it will pick up right where it left off. If possible, it's best to schedule the installation of Kiln during off-hours if you are installing on a production machine.
2.
Kiln requires some FogBugz components.
We actually launch a seriously trimmed down FogBugz installer during the setup process. Don't worry; This is totally normal :)
3.
You need to run the installer as a SQL and Windows administrator.
We make changes to Windows and SQL Server that require administrator access. If your SQL Server is on another computer, you need to take extra care to make sure your user has the right privileges.
4.
If you want Kiln and FogBugz to work together, they have to run on the same server.
At least the front-end components do. It is possible to have your DB and Mercurial repositories elsewhere.
5.
Installation of Prerequisites
requires internet access. If your server is missing any prerequisites, setup will download and install them for you. If your Kiln server does not have access to the public internet, please see this post .
3. Installer Walk-through
Welcome
4
The easy one. Just click Next because you've already got these instructions open (pat yourself on the back).
Prerequisites
If Kiln needs any supporting software installed beforehand, just click Install Prerequisites and it will launch Microsoft's Web Platform
Installer to get everything installed. This varies depending on the state of your system. If you've asked the Kiln installer to install a SQL
Express instance for you,
this step can take a while
. Go get yourself a cup of cocoa, and relax for a little while. If necessary, this may restart your server. Once it's restarted the Web Platform Installer will continue installing prerequisites. Once it is finished, you can restart the
Kiln installer.
Settings
The settings page lets you specify where to install the three main components of Kiln.
Website
The Kiln website will be linked with a FogBugz install. You can select an existing FogBugz install, or have the Kiln installer create a new
FogBugz installation. Kiln will be located at http://your.fogbugz.url/kiln .
If you want fully integrated Kiln and FogBugz, they
must
be installed on the same server.
Database
Kiln uses SQL server to store meta data about your code and code reviews. Basically, it's what we use to make the Kiln web front end work. Your code isn't stored here. You can choose any SQL Server 2005/2008 or SQL Express 2008 instance. If you don't have one available, Kiln can install and configure a SQL Express instance for you during the Prerequisites step.
Storage Service
The Kiln storage service manages the Mercurial repositories that you create while using Kiln. We strongly recommend that you install the Storage Service on the same machine as the Kiln front end. It is slightly more secure, and it reduces complexity which makes managing your Kiln installation easier.
Installation
Once you've selected these settings, installation will begin. The installer will do the following:
1. Install Kiln files
2. Launch the Kiln Storage Service installer
3. Launch the FogBugz installer to install/upgrade the FogBugz Base components
4. Configure the Kiln website and database
5. Launch Kiln in your default web browser to let you log on and install licenses
Kiln Storage Service Installer
This installer asks for some very basic information about where you want to install it, and where you want it to store your Mercurial repositories. Mercurial is
very
efficient about how it uses storage, but you will want to make sure you put your repository directory in a place with plenty of available disk space (10GB minimum, likely more).
Note: As of Kiln 2.9, the Kiln Storage Service's
KilnRepositories
folder may not be located on a network drive.
The FogBugz Installer
If you've ever installed FogBugz, you will recognize the installer and probably realize that it is seriously shortened. The only critical thing here is setting up the FogBugz user. The web components and system services for both Kiln and FogBugz will run as this user. It is also used to connect to the SQL database.
If SQL Server is on a different machine, you will want to make this a domain user.
Login to Kiln, and enter your licenses
For the duration of the beta, a 100 user license will come pre-installed with Kiln. After that, this step will take you through the normal licenses installation procedure. If you already had FogBugz, you will need to log on to Kiln with a FogBugz administrator account and enter
5
your Kiln licences on the Admin -> Licenses page. Otherwise, you will login with the default administrator account and enter your licenses.
4. Advanced Instructions
If you've gotten this far you've already mastered Windows permissions entanglement theory. That's not advanced enough for you?
Using Mixed-Mode authentication to connect to the Kiln database.
You needed to run the installer as a user with administrator permissions on the database. After Kiln is installed, you can change the connection string in the web.config file to use a specific database user, rather than a Windows user. The database user will need to be an administrator for the Kiln database. Just replace Integrate
Security=SSPI; with User Id=myUsername;Password=myPassword; . Once you've done this you can revoke permissions to the user that was setup by the installer (typically the FogBugz user).
This section will continue to be filled out as people try, and we work to support, more complex environments for Kiln.
Was this article helpful?: Yes No
6
How do I uninstall Kiln?
Currently, uninstall support is very basic.
First, uninstall the Kiln website by going to Add/Remove Programs in the control panel. Find the one titled "Kiln 1.0 (Or whichever version you have)" or "Licensed Kiln" and uninstall it.
If you are not keeping your FogBugz install, use Add/Remove Programs to uninstall it also. It is recommended that you do not remove the
FogBugz user if you're planning to reinstall FogBugz and/or Kiln on the same machine.
That's all that you'll need to do to remove Kiln and should allow it to be reinstalled in the future if you choose to try it out again, but there will be some leftover stuff that you can clean up if you want to.
All versions
Delete the %APPDATA%\KilnInstaller directory on the account used to install Kiln
Delete the kiln database
Kiln 1.1 or earlier
Remove the registry keys at HKLM\Software\Fog Creek Software\Kiln and HKLM\Software\Wow6432Node\Fog Creek
Software\Kiln
Uninstall Inno Setup and ISTool
Uninstall the Kiln Storage Service
Was this article helpful?: Yes No
7
How do I enable and view logging in Kiln 2?
Logging for the Kiln Storage Service is automatically enabled and is called errors.txt
. It is located in the directory containing your repositories which you specified during the installation process (by default: C:\KilnRepositories\errors.txt
).
Logging for the Kiln site in general needs to be enabled via the registry. You'll be adding these keys at HKLM\Software\Fog Creek
Software\Kiln\Daemon or HKLM\Software\WOW6432Node\Fog Creek Software\Kiln\Daemon if you're 64-bit.
To enable, add a new String key named LogFile with a value of the path you want to logs to be stored in (e.g.,
C:\KilnRepositories\daemon.txt
), then create a new String key named LogLevel with a value of info , critical , or debug depending on your needs.
Once you restart the Kiln Storage Service, logging will start. Log files don't roll over, however, so beware of how large these files may get if left unchecked!
Was this article helpful?: Yes No
8
How do I configure Kiln for my server?
Kiln On Demand
There are no configuration options for Kiln. We've set up everything for you. Move along. Nothing to see here.
Kiln for your Server
First, read Kiln's system requirements and installation instructions .
Running Kiln or the FogBugz/Kiln bundle in a virtual machine is not generally recommended. Since Kiln is an extremely disk-heavy application, you may experience performance degradation. Please see Can I run Kiln in a VM / Virtual Machine?
if you are considering running Kiln in a virtual environment.
The only configuration setting you are likely to want change is the database connection string in the Web.config file. It should look like this:
<add name="KilnConnectionString" connectionString="Data Source=localhost;Initial Catalog=kiln;Persist Security Info=True;Integrated
Security=SSPI;MultipleActiveResultSets=true;" providerName="System.Data.SqlClient" />
There are a few things you can change in the "connectionString" if you move the Kiln database or want to change the connection settings:
Data Source
is the address of the SQL server
Initial Catalog
is the name of the database
Integrated Security=SSPI;
indicates that you want to use Windows authentication, and the same user that runs the Kiln web application to access the database
This can be replaced with "User Id=myUsername;Password=myPassword;" if you would prefer to use SQL Server authentication
Was this article helpful?: Yes No
9
Can I have a different number of licenses for FogBugz and Kiln?
No, you can't have a different number of users for FogBugz and Kiln. We took this into consideration when deciding on pricing, which is part of why we made the bundle discount so deep (80% off for Kiln On Demand, 50% off for Kiln on your server). Thus, you would need less than 20%/50% of your users to be developers before you hit the break-even point based on the standalone price. Think of it like sort of like MS Office, sure not everyone uses Powerpoint or Access, but since its so inexpensive to have all of them (relatively speaking), you don't hesitate to make use of them when appropriate.
Another thing to keep in mind, we've found it immensely useful for customer service and management to have visibility into what's going on in the code. It helps people understand the complexity of certain problems or features, and gives them some insight as to what is going in to fixing a bug that they've found. In other words, there's utility there for people working directly or indirectly with developers, not just directly with the code.
If it's a security issue, it is easy to configure strict permissions on everything in Kiln, so no need to be concerned there.
Was this article helpful?: Yes No
10
How do I configure FogBugz and Kiln to require SSL (https)?
Follow these steps to setup SSL for FogBugz in IIS , then update your web.config in C:\Program Files\Kiln\website\Kiln , so it knows the correct url for accessing FogBugz. Make sure to change http:// to https://
<add key="FogBugzUrlPrefixOverride" value="https://your/fogbugz/url" />
Was this article helpful?: Yes No
11
I’ve got FogBugz On Demand already, how do I add Kiln to my On Demand account?
This is actually really easy. Log into FogBugz as a site administrator and go to the Admin menu and choose Your On Demand
Account . On that page, change the selection next to
Your Plan
to
FogBugz & Kiln
Once you've confirmed the plan change, you're done! Kiln is now active. Navigating to Kiln is as simple as clicking the Kiln tab above the main navigation bar in FogBugz or your account page.
If you're an existing FogBugz customer who has never tried Kiln
you will automatically get a free 45 day trial. At the end of the trial, you will have to opt-in to keep Kiln active. That means we will never charge your card without you explicitly telling us it's OK.
If you've already had a free trial of Kiln
your plan change will be reflected on your next monthly statement and you will be charged the
Bundle rate for your users, currently US$30 per user per month (volume discounts apply).
Note:
The Fog Creek Development bundle plan saves you a lot of money as compared to standalone Kiln and FogBugz accounts.
The products work so well together that we wanted it to be a no-brainer to get both.
Was this article helpful?: Yes No
12
I’ve got Kiln On Demand already, how do I add FogBugz to my On Demand account?
This is actually really easy. There are a few ways that you can do this, but we recommend that you go to the Admin menu, and choose
Your On Demand Account :
Once there, you will see the Your Plan section. It should look like this:
To upgrade to the bundle, simply click the FogBugz & Kiln option on the right (you will be asked to confirm your selection, so don't worry).
Once you confirm the plan change, you're all done! FogBugz is now active. Navigating to FogBugz is as simple as clicking the FogBugz tab above the main navigation bar in Kiln or from your account page.
Note:
The Fog Creek Development bundle plan saves you a lot of money as compared to standalone Kiln and FogBugz accounts.
The products work so well together that we wanted it to be a no-brainer to get both.
Was this article helpful?: Yes No
13
How do I link FogBugz cases to Kiln reviews and vice-versa?
NOTE:
This post is only fully relevant to Kiln 2.7 and earlier. Kiln code reviews are no longer managed through FogBugz. For more information on the new Kiln code review system, check out this article: http://kiln.stackexchange.com/questions/4836/whats-changed-withkilns-code-reviews
Just mention some variant of
review 123
, "case 123", "bug 123", or the like in your commit message, and Kiln will automatically associate it with the corresponding case in FogBugz. These forms are all completely identical, as far as Kiln is concerned; just choose whichever one gives you the best readability.
If the bug you mention is a review, then your changeset will automatically be added to the review if possible (i.e., it's in a related repository).
Cases associated with changesets in a review are also associated with any reviews that changeset is in automatically.
If you forget to link a changeset to a case at at commit time, Kiln allows you to associate cases with changesets after the fact. Simply click on the "Add Case" button when viewing the changeset you've just pushed.
Was this article helpful?: Yes No
14
How do I know which bugs have been fixed between builds?
Yes it can! Part of our new integration between Kiln and FogBugz is a FogBugz search axis which lets you specify two Tags from Kiln. Let's say you have two Changesets tagged Build_1.0.3 and Build_1.0.4 simply search for tagrange:"Build_1.0.3..Build_1.0.4"
The result set will be all cases which have been completed between those two tags.
The exact workings of this axis are as follows. If you search for tagrange:"tagA..tagB" first we will find every repository that contain both tags. Then we return all cases such that every associated changeset is an ancestor of tagB and at least 1 changeset is not an ancestor of tagA. Another way to think of this is: Bugs with changesets after tagA with no changesets after tagB. This set of cases is the set of cases which were completed between the two tags.
There is a corresponding filter "kiln - completed between" which returns an identical result set.
Was this article helpful?: Yes No
15
How do I know where my fogbugz case has been fixed?
When viewing a case that's been associated with changesets, FogBugz will display a "View Checkins" link. The checkins popup, which appears when this link is clicked, has been completely revamped in Kiln 2.0. These changes have been made to help you find your checkins much more easily.
1. Each changeset is only listed once even if it's in multiple repositories. If your changeset gets pushed to many repositories, this will significantly reduce the clutter.
2. Each changeset is displayed alongside a list of every repository which contains it. This means that at a glance, you can see which changesets have been pulled where.
3. On the bottom of the popup we dispay which repositories completely contain all changesets. This way you know which repositories contain the full fix, and which still need to pull.
4. Lastly: the most powerful bit of information. If all of your checkins are contained within a central repository, we will tell you which tags contain all of the checkins. Informally this means the first tagged changesets in which your bug has been fixed. Formally this is the
Least Common (tagged) Descendants of all checkins associated with the case.
This is just one of the new features which will hopefully make the integration between Kiln, FogBugz and your build process just that much tighter.
Was this article helpful?: Yes No
16
What exactly do Project and Repository permission levels mean?
Want do see a quick video demonstration of how permissions work? Check out our blog post on Control Who Can Access Your Code .
Kiln has a Project > Repository Group > Repository hierarchy.
Project admins are able to do everything in a Kiln project. That means they can clone and pull from repos, push to repos, create new central repos, access organize mode which allows for the creation, movement and modification of repositories and repository groups, delete repositories, configure project permissions and delete projects.
Repo admins can access repo settings page but can't can't do anything on the repository group/project level without the appropriate project level permissions.
It sounds like the best thing to do for your developers would be to give them modify permissions on the project in question. With the modify permissions they will be able to branch from this core repo, but will not be able to access any settings nor create other central repositories.
This is the primary Kiln Q&A site, but more information can be found at: http://www.fogcreek.com/Kiln/support.html
Was this article helpful?: Yes No
17
Is there a way to alias a URL to a repository?
Excellent question. Tremendously well-written. In Kiln 2, there is a new feature, Repository Aliases, that will let you do precisely that. In each project, the administrators can to create, update, and delete these aliases, which should simplify build scripts and the life of the resident build manager.
A quick fun guide to repository aliases
(Note: You must be a project administrator to participate in this quick fun guide.) Start by going to your Organize Projects page:
Above the repositories, there exists the
Manage repository aliases
link!
Click on it to bring up the Organize Aliases popup:
Let's dramatically improve our build manager lives by adding a new alias for the legacy version of FogBugz 8.6 in this imaginary universe:
18
Click Done. You should now see the alias show up inside the 8.6 repository link:
Clicking on the alias brings up a helpful information popup about it:
We can now use that URL in hg instead of the actual URL:
$> hg clone "http://localhost/FogBugz/Kiln/RepoAlias/Fog/legacy" destination directory: legacy requesting all changes adding changesets adding manifests adding file changes added 1 changesets with 1 changes to 1 files updating to branch default
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
And, when 8-7 becomes the legacy repository, all you have to do as the build manager is go back to the Organize Aliases popup and change the alias to point to the 8-7 repository. No build script modifications necessary.
Use the extra time to sip on your piña colada. You deserve it.
All this, and more, in the exciting new Kiln 2 release.
Was this article helpful?: Yes No
19
In Kiln 2, what’s the new API like?
Sure, oddly well-informed stranger! API 1.0 will provide read/write operations to some basic Kiln objects: projects, repository groups, repositories, reviews, and people permissions. A new Kiln developers website will go live describing the API in its entirety rather than me boring you here. Take a look at the
Kiln Developers website
for more details!
The new API runs over HTTP and returns JSON objects. (Not XML, if you're coming from the FogBugz platform.) As always, this Stack
Exchange will be the place to get Kiln development help. We're excited that the power of Mercurial features like hg log or hg diff will be one
HTTP request away. And we hope to continue iterating on the API as we receive developer feedback, exposing more of Kiln's functionality through it as time goes on.
Some examples of what you can do with the new API:
TA a class of 300 students, each with their set of collaborative repositories with custom permissions that could be set up with a script.
Find true love, then lose it.
Be notified from your iPhone when someone assigns a review to you.
Rename, move, branch, and manage repositories from the command prompt.
So, in Kiln 2, you should be able to develop some basic applications based on Kiln from any programming language with an HTTP library,
JSON parsing, and a good heart. We look forward to seeing what people do with it! (Good things, we hope.)
View complete documentation
Was this article helpful?: Yes No
20
Offsite backups
Update by Fog Creek Support
:
We have not tested any of the scripts mentioned with
kbfiles
or
largefiles
. Using these extensions causes certain files not to be present on your machine until you update to a given revision. If you use a filesystem copy of C:\KilnRepositories on your locally installed
Kiln instance, you have a full backup. If you are using a script to hg pull your repos from a local or an On Demand site, please see the command here which updates to all revisions to make sure every version of a kbfile/largefile is present.
There are couple of options to create off-site backups of your repositories. Essentially the core concept is to run a script on a remote server, use the Kiln API to enumerate the repositories on the kiln server and then use simple hg clone / pull commands to get current copies of the repositories on the remote server.
There are a couple of user-written scripts that do just that. The first was written by Stefan Rusek and is available here , and the second was written by Nate Silva and can be found here .
These scripts are both pretty generic and might work perfectly for your needs without modification. Alternatively you could use them as a starting point and expand the scripts to suit your own environment.
Was this article helpful?: Yes No
21
Does Kiln support web hooks?
Yup! Kiln administrators can add web hooks as useful integration points between Kiln and any number of other services.
Just choose the URL Kiln should hit and which repositories should fire the hook. Then, every time these repositories receive a push, information about the push and its changesets will be POST'ed to the URL.
The data POST'ed is a JSON payload, and the data is accessible via the "payload" POST variable. So if you're in .NET land, you'd access the JSON payload like so: string s = Request["payload"];
...and string s will contain a JSON string of the following format:
{
"commits": [
{
"author": "Ben Kamens <ben@fogcreek.com>",
"branch": "default",
"id": "16265aef917cfe137e250c4f71a4a77ff4ad0974",
"message": "This thing is taking forever",
"revision": 14,
"timestamp": "3\/23\/2010 3:42:42 PM",
"url": "http:\/\/kamens.kilnhg.com\/Repo\/Personal\/Playground\/DNForever\/History\/16265aef917cfe137e250c4f71a4a77ff4ad0974",
"tags": [
"tip"
]
},
{
"author": "Ben Kamens <ben@fogcreek.com>",
"branch": "default",
"id": "a077d19afed224dc7c46dc535d5f7e90546ed5bd",
"message": "This version is now shippable",
"revision": 15,
"timestamp": "3\/23\/2010 3:42:46 PM",
"url": "http:\/\/kamens.kilnhg.com\/Repo\/Personal\/Playground\/DNForever\/History\/a077d19afed224dc7c46dc535d5f7e90546ed5bd",
"tags": []
}
],
"pusher": {
"email": "ben@fogcreek.com",
"fullName": "Ben Kamens"
},
"repository": {
"central": true,
"description": "Picking up where the others left off",
"id": 1,
"name": "DNForever",
"url": "http:\/\/kamens.kilnhg.com\/Repo\/Personal\/Playground\/DNForever"
}
}
...which you can then parse and use however necessary in your continuous integration server or any piece of software that needs to know when Kiln receives a push.
22
The repository.id
key is the repository's ixRepo , suitable for sending to the Kiln API .
Note that the timestamp for commits are in UTC.
Please keep in mind that this data will be sent regardless of your Kiln repository's permissions settings.
Here are some instructions for testing your web hook to make sure it's firing.
Was this article helpful?: Yes No
23
How do I test Kiln’s Web Hooks?
1. Go to postbin.org (or the newer http://requestb.in/ )
2. Click "Make a postbin" to create a postbin for yourself
3. Create a new Web Hook in Kiln that points to your postbin URL.
4. Push some code to one of your Kiln repositories.
Note that data about this push will be publicly available, so do not push anything sensitive.
5. If everything worked properly, your postbin URL will now display all of the data sent from Kiln to postbin.org by the Web Hook, and it should look very similar to this example web hook data .
Was this article helpful?: Yes No
24
Can I use commit hooks to reject malformed commits?
On the client it is, see Chapter 10 of the Mercurial Book for docs that explain it reasonably well.
Was this article helpful?: Yes No
25
Best Practice: Generating build numbers
At Fog Creek, we use tags that match a regex to set the build number. For example, the current version of Kiln 2.0 that's on On Demand is generation 240, so there's a tag called Hosted_Kiln_240 . Every time we cut a new build, we make a new tag, and the build scripts know to look for Hosted_Kiln_(\d+) to set the build number.
That works great for us. We only make a couple of builds per day, and we make lots and lots of commits. But if you had, say, a continuous integration system running, it'd be incredibly annoying; your commits would get drowned out by the new tags.
The "right" thing to do is to use the changeset numbers. I say "right" because it's the only thing that will be constant across all repositories.
They just happen to be ugly.
Thankfully, if you want something that's a lot more readable and will work just fine (with some caveats), there are two solutions:
1. If you're always building from the same repository, you can simply use Mercurial's revision number. Just remember that it's not constant across repositories, so if you cut builds for the same product from two different repos, you're in for a world of pain.
Otherwise, though, you should be fine. When we first switched to Mercurial, Copilot used that scheme, and it served us well until we switched to a tag/regex-based solution.
2. If you want something similar, but more informative and (slightly) more resilient to you switching repositories, you can use Mercurial's latesttag and latesttagdistance template tags. These tags will tell you what the most recent tag was in the repository, and how many changesets sit between the changeset in question and that tag.
For example, from your project, try running hg parents --template '{latesttag}+{latesttagdistance}\n' . On my system, for example, that gives back Hosted_Kiln_240+11 , meaning that my team made 11 new changesets since we cut version 240. If you were using more traditional version numbers for your tags, it'd be pretty reasonable to just grab
{latesttag}.{latesttagdistance} to get a traditional <major>.<minor>.<bugfix>.<build> -style version number.
As I said, both of these methods are "bad" in the sense that they are repository-dependent. If you really need cross-repository build consistency, you probably really do want to suck it up and go the tagging route. But, as long as you keep the caveats in mind, this should provide you clean, easy-to-use build numbers that'll still reliably identify what changesets ended up in the build.
Was this article helpful?: Yes No
26
What are Access Tokens? Do they let me avoid using up a license on my continuous integration server?
There sure is! Starting in Kiln 2.5.170, a new feature, called Access Tokens, allows CI systems to work with Kiln, without using up a Kiln license. Access Tokens arent full-fledged Kiln accounts; they only allow cloning and pulling from Kiln repositories, optionally pushing to them, and working with the JSON API. They also run in two permissions modes: global, read-only access, which allows read-only access to the API and repositories (i.e., cloning and pulling); and global write access, which allows pushing to all repositories, plus a limited ability to edit some Kiln objects via the API.
Making access tokens is simple. To create one, just go to the Access Tokens page, click Create New Access Token, give it a name, and presto, youre done. You can change the name at any point just by clicking on the description, giving it a new description, and saving your changes. You can also toggle whether the token is read-only or read and write via the same editing mode.
So, how do you use Access Tokens? Its easy as pie. When interacting with Kiln via Mercurial, simply supply the token ID with any password (the password is ignored). When interacting with the API, simply use the access token as your Kiln token.
Thats it. Everything else works as normal.
On a build server, you can put the token in the hgrc file inside a repo's .hg
folder, or in the build user's Mercurial.ini
file.
[auth] kiln.prefix = path.to.kiln.com
kiln.username = 9f5d3162-1678-43d9-ae70-06bc4def15b9 kiln.password = anypassword
Was this article helpful?: Yes No
27
Un-Deleting Repositories
Click Admin -> Project -> Edit (next to the project with the deleted repo)
Then click "Show deleted repositories" Then you can undelete the repository.
Was this article helpful?: Yes No
28
Best Practice: Generating build numbers
At Fog Creek, we use tags that match a regex to set the build number. For example, the current version of Kiln 2.0 that's on On Demand is generation 240, so there's a tag called Hosted_Kiln_240 . Every time we cut a new build, we make a new tag, and the build scripts know to look for Hosted_Kiln_(\d+) to set the build number.
That works great for us. We only make a couple of builds per day, and we make lots and lots of commits. But if you had, say, a continuous integration system running, it'd be incredibly annoying; your commits would get drowned out by the new tags.
The "right" thing to do is to use the changeset numbers. I say "right" because it's the only thing that will be constant across all repositories.
They just happen to be ugly.
Thankfully, if you want something that's a lot more readable and will work just fine (with some caveats), there are two solutions:
1. If you're always building from the same repository, you can simply use Mercurial's revision number. Just remember that it's not constant across repositories, so if you cut builds for the same product from two different repos, you're in for a world of pain.
Otherwise, though, you should be fine. When we first switched to Mercurial, Copilot used that scheme, and it served us well until we switched to a tag/regex-based solution.
2. If you want something similar, but more informative and (slightly) more resilient to you switching repositories, you can use Mercurial's latesttag and latesttagdistance template tags. These tags will tell you what the most recent tag was in the repository, and how many changesets sit between the changeset in question and that tag.
For example, from your project, try running hg parents --template '{latesttag}+{latesttagdistance}\n' . On my system, for example, that gives back Hosted_Kiln_240+11 , meaning that my team made 11 new changesets since we cut version 240. If you were using more traditional version numbers for your tags, it'd be pretty reasonable to just grab
{latesttag}.{latesttagdistance} to get a traditional <major>.<minor>.<bugfix>.<build> -style version number.
As I said, both of these methods are "bad" in the sense that they are repository-dependent. If you really need cross-repository build consistency, you probably really do want to suck it up and go the tagging route. But, as long as you keep the caveats in mind, this should provide you clean, easy-to-use build numbers that'll still reliably identify what changesets ended up in the build.
Was this article helpful?: Yes No
29
How can I strip changesets from the central repository in Kiln?
One of Kiln 2.0's more hidden features is the ability to strip changesets from central repositories directly from Kiln. This could come in handy if, say, you misspelled a commit message, accidentally pushed it to Kiln and now want to change it; or if you accidentally added a file that contained patented code/personal information/other bad things. Strip allows you to rewrite the history of a repository to make it as if whatever you did never even happened.
Unfortunately, being able to strip your local repositories is only part of the answer - if the changeset was pushed to Kiln, it will simply reappear in your local repository the next time you pull. Kiln 2.0 allows you to strip changesets from a Kiln repository through the web interface. A backup will be created automatically as a branch of the stripped repository.
1. Pick a changeset. That changeset and its descendants will be removed from the repository - including merges, so be aware that you could create multiple heads. Copy the ID of that changeset to the clipboard.
2. Go to the repository's settings page.
3. Expand the "Strip Changesets..." section, and paste the changeset ID from step 1 into the text box. Click "Strip".
4. The changesets that will be stripped are highlighted in red - make sure that the changesets you intend to strip are highlighted, and no others. When ready, click "Strip".
5. You will be brought to a waiting page while the stripping operation takes place.
While we provide this functionality as a convenience tool, we encourage you to use it only in dire circumstances. As this post points out, stripping from the main Kiln repository can have unexpected consequences if others had pulled the changesets before you stripped them.
(An alternative is to use 'hg backout'.) It is also worth noting that the stripping operation on the website can take quite a while - have patience, and discourage other contributors from pushing or pulling during the strip.
Was this article helpful?: Yes No
30
Can I undo converting a branch repository to a central repository?
No, there are a number of implications of this that we wanted to avoid.
The easiest way to achieve the same result is to rename the current repo, make a branch from it with the original name, reparent that branch to the original parent, and delete the extra central repo.
Was this article helpful?: Yes No
31
How do I keep Kiln from showing a file in a diff?
You sure can! As of Kiln 2.4, simply check in a file called .kilnignore
in the root of your repository, using exactly the same syntax as a
.hgignore
file . Any files you specify there will be ignored when Kiln renders diffs. But don't worry: they'll be version tracked and stored just like any other file. You'll only be changing how they're shown in Kiln. So if you later change your mind, just remove the banned file from your .kilnignore
file, and it'll show up in diffs again, just as if nothing has changed.
So for example, let's say that my IDE makes solution files called LotsOChurn.solution
, that I want to ignore. I also want to ignore all of my minified JavaScript, which I always make sure ends with the extension .min.js
. In that case, to tell Kiln to ignore those files, I'd just put the following in my .kilnignore
: syntax:glob
LotsOChurn.solution
*.min.js
and they'll disappear from within Kiln.
Was this article helpful?: Yes No
32
How can I successfully convert my repository to Mercurial?
The Kiln Importer is a great tool, but it's also a bit simple: put in a repository on one end and get a repository in Kiln on the other end.
Tweaking your repository so that it's ideally set up for Mercurial workflows is left as an exercise to the user.
While we're planning to make changes to the Kiln Importer to make it more advanced, here are some principles you can apply to manually convert your repository so that it works well in Mercurial.
Convert only what you need
Some version control systems, such as Subversion, will structure the repository as a file tree such that subdirectories are used to represent individual projects. In Kiln and Mercurial, you most likely do not want to convert the entire root trunk of the source repository.
A good test for determining which paths should be independent mercurial repositories is to ask, "which path would I use to checkout code if I needed to begin work on a single project and only this project?" That's usually the path you want to use when converting to Mercurial.
For example, let's say your repository tree in SVN looks like this:
/Trunk
/CoolProject
/WebApp
/DesktopApp
/Utilities
/userscripts
/powershell
In the above example, you would probably want to have Mercurial repositories for the following paths:
/Trunk/CoolProject/WebApp
/Trunk/CoolProject/DesktopApp
/Trunk/Utilities
Although CoolProject/WebApp and CoolProject/DesktopApp are related, they probably should be independent repositories unless you always work on development together. This also helps to separate the history of WebApp and DesktopApp, which are distinct products.
We could separate the Utilities/userscripts and Utilities/powershell repositories since they may not be related, it may simply be more convenient to work on all utilities at once. Further, I'm not concerned if the history of userscripts gets mixed with the history of Powershell.
Use the hgconvert extension
The Kiln import tool will do a good job converting your entire repo, but sometimes you want to be a bit more careful with what you bring over. For example, if you had binary debugging files that you would like to exclude from Mercurial's history, you may want to do the conversion manually.
Start with the documentation for the hgconvert extension . You'll need to enable the extension before using it. You can enable it by adding the following lines to your Mercurial.ini file:
[extensions] hgext.convert=
You can use hg convert to convert from many different sources in very precise ways. You can even use hg convert against other
Mercurial repositories.
Use hgconvert filemaps to exclude files
While you can use an .hgignore file to exclude certain files from your repository (see below), it's not going to help remove files from your repository's
history
. Do remove files and directories from the entire history of your repository, you need to use hg convert -filemap .
33
The documentation for --filemap is a bit sparse, so I'm going to include a few additional details here.
The filemap is a text file that you'll reference during the conversion. It allows you to specify multiple lines with exclude , include , or rename directives. Note that include will only include the files that are specified in include and will automatically exclude anything not included in an include statement. If you're using filemap to replicate .hgignore, you'll probably stick with exclude .
Let's say you create a filemap at C:\Temp\filemap.txt with the following contents: exclude "Test.txt" # exclude the file Test.txt from the
# converted repo exclude "libs/abc.dll" # use unix-style paths, regardless of OS exclude "subdir" # exclude all files from this subdirectory
In the example above, the first line will exclude
Test.txt
. Note that filenames are case sensitive. The second line will exclude
abc.dll
, which is in the subdirectory
libs
. Note the use of unix-style paths, which is required. The third line will exclude the entire subdirectory called
subdir
.
When I'm ready to run hgconvert, I can do so with a command like the following:
> hg convert --filemap C:\Temp\filemap.txt
http://path/of/source/repo .\DestinationPath
After running hg convert , you will have a new repository that excludes the files you specified from its entire history.
Use kbfiles and kbfconvert (largefiles as of Kiln 2.9)
NOTE: Kiln 2.9 ships with support for the LargeFiles extension, which is now part of Mercurial and not exclusive to Kiln. Most of the following still applies, but you should use LargeFiles instead of KBFiles. See How do I use the Mercurial LargeFiles
Extension?
for more details.
Kiln ships with an extension called
kbfiles
which can be useful for storing large binary assets in your repository. If you have large files in your repository for which having an atomic diff is unimportant, it's recommended (and sometimes required) that you use kbfiles.
For example, let's say you store documentation.pdf, a 35MB binary file, in your repository. Each time you commit a change to documentation.pdf, unless you have added the file as a
bfile
, Mercurial is going to diff the file to try to figure out exactly what changed. This is very resource intensive on Mercurial, and very often unnecessary. Instead, we use
kbfiles
, which will still store each revision of the file, but it won't try to diff it because a diff would be meaningless.
See How do you use kbfiles?
for how to use kbfiles and additional explanation of why you want to use it. That documentation will give you a good idea of how to add kbfiles to an existing repository. I want to focus here on the conversion features of kbfiles with kbfconvert .
You can use kbfconvert to convert your repository to one with a new history so that specific files or files of a particular size are always added as kbfiles for the entire history of the repository. This is preferred if you're going to be pushing large binary assets to Kiln.
If you want to convert a repository to use kbfiles purely based on size, you can use a command like the following, which will automatically convert all files larger than 10 MB to use kbfiles:
> hg kbfconvert sourcerepo destrepo --size 10
What if you want to add files not based on size, but explicitly by file name? You can use kbfconvert to specify the names of individual files to add as kbfiles. The files you specify get added even if they are under the size specification. In the following example,
TestSearch3.png
,
Test.txt.orig
, and
subdir\file2.txt
are all going to become kbfiles in the converted repository, even though they are smaller than the specified file size of 1000MB.
> hg kbfconvert .\SourceRepo .\DestinationRepo TestSearch3.png
Test.txt.orig subdir\file2.txt --size 1000
Use a command like the above to explicitly convert specific files to using kbfiles in the converted repository.
34
Use an .hgignore file
Most Mercurial repositories benefit from an .hgignore file because it helps remove unnecessary cruft from the repository. For example, a
Visual Studio solution is going to include .pdb debugging files and compiled binaries that don't need be included in the repository. In this case, an .hgignore is essential.
The documentation for hgignore is a good start. You might be able to search around for a sample .hgignore that matches the development environment for the project you're working on, but be careful that it's not too liberal in excluding files. For example, see this example
.hgignore file for Visual Studio projects which we created. You can add the .hgignore file after the conversion, but it is not used by the hg convert process (unless of course you're converting a Mercurial repository that included an .hgignore file in its history).
Bringing it all together
We've gone over quite a few techniques above. Here's a set of practical steps you can apply to convert your repositories so that they're in good shape for use in Kiln.
1. Identify which paths in your source version control system are going to be converted into individual mercurial repositories. You'll want to run the following steps for each repository.
2. Create a filemap for the repository so that you exclude files that do not need to be in the converted repository.
3. Run hg convert with the filemap you created so that you now have a Mercurial repository with only the files you need to actually work on code.
4. Run kbfconvert against the converted repository from step 3 such that some files, specified either explicitly or by size, are included as kbfiles. The resulting repository will be much friendlier to Kiln and Mercurial.
5. Add an .hgignore file to the converted repository from step 4 so that going forward, the repository only contains what it needs. Don't forget to hg add and hg commit the .hgignore file!
6. Push the repository to Kiln.
Once you do the above steps, you should be good to go!
Was this article helpful?: Yes No
35
How do I import my files into Kiln from Visual Source Safe (VSS)?
For mainstream version control systems, such as Subversion, CVS, Git, Monotone, Perforce, and Bazaar, you can use the conversion tools that come with Mercurial to turn your historic source tree into a Mercurial-based one.
Doing so involves three steps:
1. Enable the convert extensions in your Mercurial.ini
(Windows) or ~/.hgrc
(everything else), by adding the line convert= to your [extensions] group.
2. Run hg convert <source> <target> , where <source> is the location of the old repository, and <target> is the name of the local Mercurial repository you want. For example, if my Subversion repository were at svn://source/svn , then I might run hg convert svn://source/svn source
3. Create a new repository in your Kiln install to hold the converted source code. For the purposes of our example, we'll say that that repository is http://my.fogbugz.com/kiln/Repo/1/Repositories-Source
4. Push to the newly created repository.
cd source && hg push http://my.fogbugz.com/kiln/Repo/1/Repositories-Source
Update:
Please try our "Import your existing Subversion/Git/Mercurial repository (or even a plain old directory of files on your local machine) into Kiln" tool by clicking the "
Download and run the Kiln Import tool
" link on any Empty Repository page.
We do not currently have plans to support more esoteric version control systems such as Visual SourceSafe or Vault. In the case of those systems, you can either create a new Mercurial repository and copy your source over, losing your history, or you can write your own tool to handle the conversion. We are aware that this solution is suboptimal, and hope to have a better solution available in the future.
Was this article helpful?: Yes No
36
How to import a subversion repos with active branches
hg convert actually makes this pretty easy. There is a config option called clonebranches that you just need to set to true, and it will make a separate repo for each branch: hg convert http://url.to/my/svn/repo imported-branches --config convert.hg.clonebranches=1
What you will end up with looks like this: imported-branches/
.hg/ # ignore this .hg, you won't need it
default/ # default branch, a.k.a. trunk/
.hg/ # notice, no files in here yet. run 'hg update' to get files
feature_a/ # all of your branches will be there own repos now
.hg/
feature_a/
.hg/
version-2.1/
.hg/
version-2.0/
.hg/
version-1.0/
.hg/
In case it's not clear,
you'll have a separate repo for each branch
. They'll all be nested under another repo. Don't bother pushing this parent repo, it won't have anything in it.
Once you have the corresponding repos created on Kiln, just push each of the repos that you want to keep: cd imported-branches hg push -R default https://example.kilnhg.com/Repo/Project/Group/devel hg push -R feature_a https://example.kilnhg.com/Repo/Project/Group/feature_a hg push -R feature_b https://example.kilnhg.com/Repo/Project/Group/feature_b hg push -R version-2.1 https://example.kilnhg.com/Repo/Project/Group/2-1
...etc...
For the branches you don't want, you can just delete them, though it wouldn't hurt to push them to Kiln, just for posterity's sake. You could keep them in a separate repository group.
Note that Mercurial and Kiln will both do the right thing, and recognize that these branches are all related. You'll be able to see differences between them on the Outgoing tab in Kiln, and should be able to pull and push between them locally with Mercurial.
Was this article helpful?: Yes No
37
Importing a subversion repository on a Mac
First I installed subversion, mercurial, and the subversion-python26bindings using macports .
sudo port install mercurial sudo port install subversion sudo port install subversion-python26bindings
Following the Mercurial instructions for repository importing, I created a .hgrc text file in my home directory and added these lines to enable the convert extension in mercurial:
[extensions] hgext.convert=
Next I created an author map with the following lines to convert my unix user name to a new mercurial user name: johnknox=John Knox <john@fooco.com>
I then imported my subversion repository trunk into a mecurial repository named myHg: hg convert --authors ~/hgUsername file:///Users/johnknox/mySvn/myProject/trunk/ myHg
I moved into the new myHg repository and updated (oddly, no files were present except the .hg until the update) cd myHg hg update
I then checked that my history was properly imported hg log Classes/mySourceFile.m
Finally, I pushed the repository into Kiln (see kiln for exact details):
hg push "https://John Knox@fooco.kilnhg.com/Repo/Repositories/Group/myProject"
Was this article helpful?: Yes No
38
Import git repository into Mercury/KILN
The easiest way to move between Git and Mercurial is to use hg-git . The easiest way to install it, from the hg-git page:
The easy way
Run easy_install hg-git, then add make sure the following is in your ~/.hgrc:
[extensions] hgext.bookmarks = hggit =
...and that's it!
Once it's installed, you can just run:
$ hg clone git://url/to/your/git/repo.git repo_hg
Once it's cloned, you just need to push it to Kiln:
$ cd repo_hg
$ hg push https://example.kilnhg.com/Repo/Project/Group/Repo
That's it!
Was this article helpful?: Yes No
39
How do I get a log of the Kiln Repository Import?
For Kiln 1.2+
After running the importer, the log will be at
%TEMP%\KilnImportLog <date> <time>.log
For Kiln 1.1
You can do that by using the windows Run command and typing in:
\path\to\KilnImporter.exe "kiln:import?log=true"
If it crashes, please submit the crash report. There will be no log file in this case.
If it fails to log in, you can click cancel. Then the log file will be at "%TEMP%\KilnImportLog " that you can send to us here at Fog Creek.
If it fails more seriously, without crashing, the location of the log file will be displayed in the importer, and can be copied if necessary.
Privacy note!
For older version of Kiln, the log includes usernames and passwords. Please replace your password with something generic before sending us your log files.
Was this article helpful?: Yes No
40
Selectively converting SVN branches
It doesn't seem to be documented anywhere that I can find (even on the Convert extension page ), but it seems to be the case that hg convert --branchmap will do what you want here.
Set up your branchmap.txt
as follows:
Unwanted_Branch1 ### THERE IS A SPACE AFTER 'Unwanted_Branch1'
Unwanted_Branch2 ### THERE IS A SPACE AFTER 'Unwanted_Branch2'
Note: Make sure to put a space after the name of the branch, or it will complain about not getting a key/value pair. Also, make sure there is no newline at the end of the file, or it will also complain.
Then run your convert as you have been, adding --branchmap branchmap.txt
.
You can also rename branches, if you want, using the branchmap:
Old_Branch1 New_Branch1
Old_Branch2 New_Branch2
Unwanted_Branch1 ### THERE IS A SPACE AFTER 'Unwanted_Branch1'
Unwanted_Branch2 ### THERE IS A SPACE AFTER 'Unwanted_Branch2'
Any branches you don't specify in the branchmap will be imported with their current name.
Was this article helpful?: Yes No
41
What’s the best way to adapt our existing Subversion project layout to Mercurial using Kiln’s Project > Repo Group > Repo heirarchy?
Your intuition is right all the way down.
In Subversion, storing lots of different projects in a single repository is commonplace. In Mercurial (and other DVCSes), storing one project per repository, and having lots of repositories, makes far more sense. That's why Kiln's repository interface is optimized to make it easy for you to organize your repositories in a meaningful way by project, group, and repo. So, at a base level, a normal Kiln install corresponding to your existing Subversion repositories would have at least two repositories, ProjectA and ProjectB .
There are several different ways to do branching in Mercurial, but the one we like best, and have put the most effort into supporting for Kiln
1.0, is to use one repository per branch. In this scenario, you would end up with four repositories in your example: ProjectA and
ProjectABranch , and ProjectB and ProjectBBranch .
In answer to Kiln and FogBugz project correspondence:
in general
, we've found that making Kiln projects correspond to FogBugz projects is the right way to go, but we have exceptions in our own install in both directions (Kiln projects lacking a corresponding FogBugz project and FogBugz projects lacking Kiln ones). So it's likely you'd have two Kiln projects, each with two repositories, in your example. We've even made it so that you can link Kiln Projects to FogBugz projects, which sets the default project for code reviews on that repo.
Now, if you have an existing monolithic Subversion repository you converted, and you've decided that you want to break that into several smaller Mercurial repositories, I have good news and bad news. The bad news is that our importer tool cannot currently help you with that, so you're going to need to use the Mercurial command-line converter; and that the converted repositories will be "different" from the original, meaning that you'll need to re-create them in Kiln and re-clone them locally once the split is complete. The good news is you'll need to do that at most once, it's fast, it's pretty easy, and it'll make your life much better down the road.
To do it:
1. Figure out how you want to split your repository. Hopefully, you have two or more directories, called (e.g.) foo/bar/ProjectA and foo/bar/ProjectB , that correspond to the projects you want to split out.
2. Make a file called filemap-projecta.txt
and put the following into it: include foo/bar/ProjectA rename foo/bar/ProjectA .
Note that you should use Unix paths, even if you're doing this on a Windows system.
3. On a clone of the repository that I'll assume is called OriginalRepo , run hg convert --filemap filemap-projecta.txt OriginalRepo ProjectA
4. Go into the newly-created ProjectA repository, run hg up , and check the result. With luck, you should find that everything under foo/bar/ProjectA is there, and is now in the root of the repository.
5. Repeat for other projects you want to split out, changing the lines in filemap-projecta.txt
appropriately.
6. Create repos in Kiln for each of the converted repositories.
7. Push your new repositories into Kiln.
That's it. Please let me know if you have any other questions.
Was this article helpful?: Yes No
42
I have absolutely no clue how to get started with Mercurial. Can you please help me?
We're really happy to announce that we now have a really great introduction to Mercurial, called HgInit , available at http://hginit.com
. It walks you through from knowing nothing about about Mercurial—or even nothing about source control—to knowing all the basics of Mercurial usage. If you're not sure how to get started, give the tutorial a try. It'll help you realize how easy Mercurial is to use, and you'll be all set up to start getting the most out of Kiln.
Was this article helpful?: Yes No
43
How do I use TortoiseHg? I have no idea.
There is actually a pretty decent quick start guide for TortoiseHg here: http://tortoisehg.bitbucket.org/manual/0.9/explorer.html
...as well as Joel's generic Hg tutorial, hginit.com
.
In general, there are two ways to interact with TortoiseHg. The first way is through its Explorer integration. When Tortoise is installed, it also installs a bunch of special hooks into Windows Explorer that allow it to display useful information about your repository. The details are described in the link above, but as an overview it shows:
1. Overlays on the icons for files/folders inside a repository (shows you the state of those files and folders)
2. New options in the Windows context menu (the one you get by right clicking on something in Explorer) to give you Mercurial controls.
When you right-click inside a repository, you get access to the most commonly used commands.
In addition, you can interact with TortoiseHg through the command line. Most people familiar with Mercurial are used to typing commands like: hg commit -m "Fixing mixed line endings that were causing diffs to look crazy"
Tortoise provides a GUI for nearly every Mercurial command. It can be accessed by replacing hg with hgtk . To get the GUI for the commit command in the previous example, you would type: hgtk commit
The GUI gives you a place to enter a commit message, and a bunch of other useful controls (this is the GUI I use most frequently). The GUI that is least useful, for me, is the one the deals with push/pull/update. I simply find it easier to use the command line interface for these commands.
I would recommend trying them all out to find out which ones are most useful for you. For a day, simply replace your hg commands with hgtk . This should help you figure out which interfaces actually help you the most.
Was this article helpful?: Yes No
44
Doc on how to best configure/use TortoiseHG with Kiln?
Configuration should happen automatically when installing the Kiln Client from your Kiln installation. This'll automatically hook everything up and give you all of the Mercurial extensions that we recommend.
We're still working on documentation for best practices (with TortoiseHG, FogBugz, and everything else), so feel free to post any discoveries of your own here (help us out and we'll do the same!). There is also some documentation about our custom Mercurial extensions in your Kiln install -- just click on Resources | Kiln Client and Tools .
Was this article helpful?: Yes No
45
Mercurial Branches and Kiln’s Forks
There are a few issues you're encountering.
Mercurial has a specific command, called hg branch , that creates something called named branches. Mercurial tools historically did not interact with named branches in a user-friendly manner, and named branches have historically had very confusing and hard to understand behaviors: closing and abandoning branches was problematic, the meaning of the tip changeset and your tags became extremely complicated, and so on. At the same time, I'd be the first to agree that having some type of named branches is very useful.
What Kiln attempts to do is to obviate the need for named branches by making it very easy to have lots and lots of clearly named and wellorganized related repositories on the server. We've opted to call those repositories "branch repositories," since their goal is to allow you to have a branch for experimenting on a feature/storing code for later review/etc. (Our terminology of calling them branch repositories, but having the action to make them be called "fork", is a usability bug that I think we need to fix.) All repositories in Kiln, whether branch repositories or central, are full-standing, independent, and (by default) only have the default branch. (You'll see it with a green background right next to tip when you're viewing a repository's history.)
What we encourage you to do is to keep separate branches of development in branch repositories in Kiln, forked off the main repository, rather than using Mercurial's named branches. In addition to the fact that tools support this workflow better, it becomes a lot easier to know what branch you're working with (just see where you cloned from), becomes trivial to discard changes (delete the branch repository), and makes it easy to try experiments without cluttering up the "real" repository's history.
So:
we strongly encourage you
not
to use Mercurial named branches. We instead encourage you to use Kiln's branch repositories to make branch management easy, and to use a clone of a branch repository when you need to contribute to a branch.
If you really
do
want to use named branches, Kiln fully support them. You can filter to just a single branch head by selecting a branch from the "branches" drop-down menu when viewing a repository's history.
Was this article helpful?: Yes No
46
Kiln Branch and Merge How-To
One of the best things about DVCS in general is that branching actually works really well. Branching works well because merging works well. This kind of makes sense to anyone who has used Subversion or most other centralized version control systems. It's never the branching that's the problem; it's that gigantic scary merge back to trunk. Sort of like that adage, "it's not the fall that kills you, it is the sudden stop at the end." But I digress...
There are generally two reasons to create branch repositories in Kiln:
1. You want to work on a feature, but you don't want to impact other developers working in your "trunk" repository.
2. You want to create a long-running branch for yourself or another developer (workspace). The workspace allows you to work without disrupting anything that is going on in the "trunk" repository. This facilitates the "review everything before it goes into trunk" codereview process.
To branch in Kiln, you need to be logged into the Kiln web interface and browsing your repositories. Each repository has a small context menu marked by the blue arrow, and from that menu you can create a branch repository:
You just need to give the branch a name. Kiln will copy the contents and history of the repository to the new branch.
It is important to reiterate here that the branch you just created is actually a full-fledged repository. You work with it just like you would any other repository. That starts with cloning. When I am working in a branch, I usually just move my copy of the "trunk" repository out of the way by renaming the folder on my machine (e.g., kiln -> kiln-trunk ), and then clone the branch repository to the old trunk location. That way I don't have to change anything in my development environment.
> hg clone http://your.fogbugz.com/kiln/repo/my/kiln/branch kiln
Now you're ready to start working and making changes. As always, you should commit your changes locally and then push them to the
47
server. This acts as a backup, plus it allows you to collaborate with your teammates by all cloning/pulling/pushing from the branch repository, if desired. While you are working in the branch repository, you can make whatever changes you need without fear of destabilizing the development work that is continuing in the "trunk".
Once you've finished your work in the branch repository, you need to get ready to merge back into "trunk". This is where the power of
DVCS comes in, but it is also a bit different than what you are used to if you are coming from a typical, centralized VCS.
Because you have a complete repository on your machine that shares history with the repository you branched from, you can actually perform the merge on your machine, and record that action in source control. The fact that you have both the state of the files and the changes made during the merge in source control means it is nearly impossible to lose information during the merge. You can always roll back and re-merge if anything goes wrong.
To perform the merge, you'll first want to pull the changes from the "trunk" into your local repository and merge those changes with the changes you've made.
> hg pull https://your.fogbugz.com/kiln/repo/my/kiln/trunk pulling from https://your.fogbugz.com/kiln/repo/my/kiln/trunk searching for changes adding changesets adding manifests adding file changes added 4 changesets with 5 changes to 4 files (+1 heads)
(run 'hg heads' to see heads, 'hg merge' to merge)
> hg merge
4 files updated, 0 files merged, 0 files removed, 0 files unresolved
> hg commit -m "merge"
Once this is done, you will have saved, in your local repository, all of your changes plus all of the changes that have been going on in the
"trunk" repository. You can now push your changes to the "trunk" repository and your branch repository without conflict.
> hg push https://your.fogbugz.com/kiln/repo/my/kiln/trunk pushing to https://your.fogbugz.com/kiln/repo/my/kiln/trunk searching for changes kiln: successfully pushed 2 changesets
> hg push pushing to https://your.fogbugz.com/kiln/repo/my/kiln/branch searching for changes kiln: successfully pushed 5 changesets
These pushes will ensure that all of the changes that were in the branch are now included in "trunk" repository on the server and vice versa.
You now have the choice to either remove the branch repository, or keep it around if you plan on continuing development there. You must be an administrator to remove a repository, but you get to it through the Settings tab in the repository view:
48
Was this article helpful?: Yes No
49
Where can I find the Kiln Client and Tools?
Open up a browser and login to your Kiln website. In the upper-right corner you'll see a menu titled "Resources." Click that and choose
"Kiln Client and Tools."
Alternatively, you can go directly to: http://[your_kiln_url]/Tools/Downloads/KilnClient
Note: Use https for Kiln On Demand.
Was this article helpful?: Yes No
50
What is the Kiln Client?
Benjamin's answer here should suffice: http://kiln.stackexchange.com/questions/118/what-is-the-difference-between-tortoisehg-andkilnclient , but the bottom line is that the Kiln Client is just TortoiseHg with a number of settings pre-configured and a couple Mercurial extensions that improve Kiln usability.
Was this article helpful?: Yes No
51
What is the difference between TortoiseHg and KilnClient?
The TortoiseHg that ships with KilnTools is no different from that you'd download directly from the TortoiseHg project. We do bundle a few extra extensions with it, and if you lack a Mercurial.ini file, we will set up one for you, but otherwise, there is (currently) no difference.
There is one extension you do likely want to enable, called kilnauth . This extension will use your Kiln cookies to log into Kiln, meaning that you only need to type your login and password once per Kiln installation that you access. To add it, add the line kilnauth= to your [extensions] section.
Was this article helpful?: Yes No
52
What do the Kiln extensions do?
We bundle a number of Mercurial extensions with the Kiln Client in order to improve your Mercurial experience. Here's a list of the extensions we bundle and what they do: big-push
Helps pushing of large repositories by adding the --chunked flag to hg push . Using --chunked helps avoid timeouts and other network issues.
caseguard
Guards against case-insensitive file collisions in Windows.
fetch hg fetch does a pull and update or pull, merge and commit, depending on which is necessary. It is closer to svn update and helps the transition from SVN to Hg.
gestalt
This extension attempts to help new Mercurial users by providing several commands to help learn how Mercurial works. The primary command provided is "hg next", which shows an overview of your local repository, its relationship and status to its parent, and what next actions you may wish to consider performing.
kbfiles
Improves support of large binary files in Mercurial by storing those files in a separate, centralized store on the server.
kilnauth
This extension knows how to capture Kiln authentication tokens when pushing over HTTP. This means you only need to enter your login and password once; after that, the FogBugz token will be stored in your home directory, allowing pushing without a password.
kiln
This extension allows you to directly open up the Kiln page for your repository, including the annotation, file view, outgoing, and other pages. Additionally, it will attempt to guess which remote Kiln repository you wish push to and pull from based on its related repositories.
nobranch
Gently suggests using Kiln's branch repositories instead of Mercurial's named branches.
Was this article helpful?: Yes No
53
I heard Kiln added kbfiles support in 2.0! What does that mean?
The Problem
Mercurial uses a lot of memory to store large files. If a repository is large enough it can't be pushed or cloned! The problem is that
Mercurial stores files by computing the changes from one version to the next. This works great for code files because normally only a few lines of a file are changed. It doesn't work well for large binary files because commonly the changes from one version to the next will be dramatic.
The other problem is that cloning can take a long time. If someone added a two gigabyte file into your repository three years ago, and then removed it, you still have to download that file everytime you clone the repository.
The Solution
kbfiles! Based upon the work of Greg Ward, kbfiles stores large files outside of the Mercurial repository to avoid the out of memory problem. kbfiles support has been tightely integrated into Kiln and Mercurial. All of the commonly used Mercurial commands (and many others) work with bfiles.
To speed up cloning only kbfiles at the tip are downloaded. Older versions of the kbfiles are downloaded when they are needed. Also kbfiles keeps a cache of the bfiles you have downloaded so you won't have to download them again.
When To Use kbfiles
If your repository is larger than a couple hundred megabytes you should consider using kbfiles. If you decide to convert to kbfiles then files larger than about 5-10 megabytes should be stored as bfiles.
Using kbfiles
Read http://kiln.stackexchange.com/questions/1873/how-do-you-use-bfiles/1874#1874
Was this article helpful?: Yes No
54
How do you use kbfiles?
---Update! Use LargeFiles Instead!---
KBFiles has been replaced by it's successor, LargeFiles . Kiln currently (as of 2.9.x) still supports KBFiles, but the extension is no longer being developed and may stop working in a future version of Kiln. LargeFiles is a Mercurial extension, so it will be maintained and kept up to date by the Mercurial community.
---End of Update---
.
If you are still using kbfiles, you can read on, but please consider converting to LargeFiles as soon as possible.
How It Works
Before we get into using kbfiles we need to learn a little about how kbfiles works. For every bfile a standin file is stored in your repository. If you have a file bar/foo then the standin will be .kbf/bar/foo. The standin stores the SHA1 hash of the bfile. When you clone a repository first the Mecurial repository is cloned, then we look through all of the standins and download the file with the correct SHA1 hash from Kiln.
Using kbfiles
Commands like clone, commit, push, pull, and update all work with kbfiles without any new options. The following Mercurial commands work with kbfiles: add, archive, backout, bisect, clone, copy, fetch, forget, incoming, log, merge, outgoing, remove, rename, revert, status, summary, update, and verify. The Kiln web interface is exactly the same for kbfiles repositories as it is for normal repositories.
Working with a kbfiles repository is very similar to working with a normal repository. For example the following sequence of commands works on a kbfiles repository exactly like it would on a normal repository.
hg clone http://path-to-repo-on-kiln kbfilesrepo cd kbfilesrepo
<edit a bfile> hg commit -m 'Updated a bfile' hg pull hg merge hg commit -m 'Merged' hg outgoing hg push
Creating a kbfiles Repository
We still need to create a repository that uses kbfiles. To use kbfiles with an existing repository you will need to convert the repository to a kbfiles enabled repository. The conversion is simple with the kbfconvert command, for example: hg kbfconvert sourcerepo destrepo --size 10
This converts sourcerepo to destrepo. Any file larger than 10 megabytes will be stored as a bfile. Run hg kbfconvert --help for more information about the command. The conversion might take a few hours, but you only have to do it once.
Adding New kbfiles
Adding is a little different with kbfiles because you need to specify whether the new file should be stored as a bfile or a normal file. Add the
--bf option to specify that a file should be added as a bfile, for example: hg add --bf movie.avi
The command will add movie.avi as a bfile. Read hg add --help for other kbfiles options. You can also specify a size and a pattern in your hgrc file. Any file larger than that size in megabytes or that matches the pattern will be added as a bfile instead of a normal file. Below is an
55
example kilnbfiles section of an hgrc file.
[kilnbfiles] size = 5 patterns = glob:**.avi
Now any file added which is larger than 5mb or has the extension .avi would become a bfile. These options are only used on repositories which already have a bfile, normal repositories will not be affected.
Using Normal Repositories With kbfiles Enabled
The kbfiles extension should be left on even when you work with normal repositories. It will not change how normal repositories work, but in some cases it might change the output of a command slightly. For example hg outgoing will now print "Searching for changes" twice.
What Doesn't Work (Yet)
TortoiseHg integration with kbfiles did not make it in Kiln 2.0. You can't corrupt your kbfiles repository with TortoiseHg, but most of the commands will not work. Using TortoiseHg with kbfiles is not recommended even though some parts of it might work.
Some Mercurial commands don't work with kbfiles. For example hg serve won't work correctly. kbfiles repositories can only be pushed or pulled locally or through Kiln. Pushing or pulling through a repository on a networked drive will not work properly.
Was this article helpful?: Yes No
56
How do I use the Mercurial LargeFiles Extension?
Should I use LargeFiles at all?
Probably not. If you don't read anything else on this page, then read this: The benefit of LargeFiles is to save some bandwidth on push/pull/clone commands and save a few CPU cycles when making a commit. This comes at a cost though! LargeFiles is considered a "last resort" extension for Mercurial because it breaks the D in DVCS ("Distributed Version Control System").
There is a very specific problem that LargeFiles is designed to solve: in the case where a repository has binary files which change frequently, the changesets can get
very
large because binary files are not very easy to diff or to compress. LargeFiles basically solves this problem by allowing certain files to be treated in the same way that Source Control Systems like Subversion treated them: as snapshots of the file at certain times. Then when you do a pull, clone, or update command, you only get the snapshots of the LargeFiles that correspond with the relevant revision. This means you do not have a full copy of the repository on your local machine.
You rely on the central repository (on Kiln) to store all the revisions of the LargeFiles and only pull them over the network when you update to a revision that needs them. This saves bandwidth and some CPU cycles.
I understand the cost/benefits trade-off, now how do I use LargeFiles?
Great! Are you sure? Go read the previous section one more time and be sure you really need LargeFiles. I'll wait... Okay, you seem pretty sure, so let's proceed.
To use LargeFiles you just need to enable the extension it and start adding files with the '--large' parameter like 'hg add --large largefile.pdf'. You might already have a bunch of binary files that you want to convert to be large files instead, which means you'll have to convert the repository.
NOTE: Once you convert your repository to use LargeFiles, it will no longer be related to the original repository. Because of this, you'll want to choose to do the conversion at a point in time when your entire team can switch to using the newly-converted LargeFiles repo.
Turning on the LargeFiles extension
Neither Kiln nor Mercurial will enable this extension by default when you install them. In order to turn the extension on you will need to add the following lines to the extensions section of your mercurial configuration file :
[extensions] largefiles =
I
highly
recommend that you
enable this on a per-repository
basis, meaning enable it in the .hg/hgrc file in the repository rather than the user or global mercurial configuration file.
Do I have to convert my existing KBFiles-enabled repositories?
No, you don't have to convert your repositories. KBFiles is still supported by Kiln 2.9. However, LargeFiles is the successor to KBFiles so there will be no more updates or bug-fixes for KBFiles. Additionally, LargeFiles resolves an issue that existed in KBFiles which reduced the performance of many hg commands. So, it is not strictly required but it is highly recommended that you switch to LargeFiles to avoid the performance impact of KBFiles and to receive any code updates to the extension.
How do I perform the conversion from KBFiles to LargeFiles?
First, you'll need to be sure you have the latest version of the Kiln Client and Tools. You can download this from the Kiln page under
"Rescources". Once you have this installed, the conversion is a simple two-step process. Each of these extensions have methods to convert from a normal repository to one using the extension and vice versa, so it is through these commands that we will perform the conversion.
You need to first convert from a KBFiles-enabled repository to a normal one, and then convert that normal repository to a LargeFilesenabled one. The following two commands will perform these conversions (the '--size 10' parameter in the second command indicates that any file over 10MB should be converted to a LargeFile. See the LargeFiles page for more complex patterns): hg kbfconvert --tonormal /your/kbf/repo/location /temporary/normal/repo
57
hg lfconvert --size 10 /temporary/normal/repo /new/largefiles/repo
Now you have a new LargeFiles repository with all the same data as was in your original repository! You can push this new repository into
Kiln and get everyone to start using it. The temporary repository created by the first command can safely be deleted from your harddisk, and it would probably be wise to delete the original KBFiles-enabled repository from Kiln to ensure that everyone switches to using the new LargeFiles repository (don't worry, kiln doesn't delete the data from the repository, it just marks it as deleted. You can recover it later if anything goes wrong).
How do I enable LargeFiles on a normal repository?
First, you'll need to be sure you have the latest version of the Kiln Client and Tools. You can download this from the Kiln page under
"Rescources". Then you just need to convert the repository with the following command (the '--size 10' parameter indicates that any file over 10MB should be converted to a LargeFile. See the LargeFiles page for more complex patterns): hg lfconvert --size 10 /your/normal/repo /new/largefiles/repo
Now push this new repository into Kiln and start using it! You can delete the original KBFiles-enabled repository from Kiln to ensure that everyone switches to using the new LargeFiles repository (don't worry, kiln doesn't delete the data from the repository, it just marks it as deleted and makes it inaccessible. You can recover it later if anything goes wrong).
Was this article helpful?: Yes No
58
How do I clear kilnauth cookies?
You can run hg logout on the command line to clear your cookies once, and you'll have to login when you run your next push / pull / inc / out command.
If you'd like to
permanently
disable kilnauth, you can simply edit your Mercurial.ini file and remove the line that starts with "kilnauth=".
Mercurial.ini should be found in your home directory (C:\Documents and Settings\{username} on XP...)
Was this article helpful?: Yes No
59
How do I use kilnauth from Cygwin?
Make sure you're using kilnauth. Then use cmd (which will allow interactive login) to authenticate with Kiln once. Finally, copy the
_hgcookies from your Windows home directory to your Cygwin home directory.
cp /cygdrive/c/Documents\ and\ Settings/[YOUR USER NAME]/_hgcookies ~
Was this article helpful?: Yes No
60
How can I install Kiln’s Mercurial extensions manually?
Sure. It's actually quite simple:
1. Grab the extensions themselves by clicking on Resources -> Kiln Client and Tools
2. Download the extensions zip bundle and extract it to your favourite location.
3. Open the file .hgrc
in your home directory. If it doesn't exist, create it.
4. Add a section called [extensions] if one does not already exist
5. Add one line for each extension you wish to include that names the extension and points to where on disk you've stored it
For example, if I wanted to use all 7 extensions, and I had saved them to ~/KilnExtensions , then my .hgrc
might look like this:
[ui] username=Your Loginname <you@example.com>
[extensions] gestalt=~/KilnExtensions/gestalt.py
kilnauth=~/KilnExtensions/kilnauth.py
kilnpath=~/KilnExtensions/kilnpath.py
big-push=~/KilnExtensions/big-push.py
kiln=~/KilnExtensions/kiln.py
caseguard=~/KilnExtensions/caseguard.py
kbfiles=~/KilnExtensions/bfiles/kbfiles
[auth] kiln.prefix=yoursite.fogbugz.com
kiln.username=Your Loginname
[kiln_scheme] kiln=http://yoursite.fogbugz.com/Kiln/Repo
Of course, there are a plethora of other extensions for Mercurial, both built-in and third-party. You might have others under the "[extensions]" section.
If everything worked correctly, you should be able to pull up the help documentation by typing hg help extensionname . For example: gozer:~ benjamin$ hg help kilnauth kilnauth extension - stores authentication cookies for HTTP repositories
This extension knows how to capture Kiln authentication tokens when pushing over HTTP. This means you only need to enter your login and password once; after that, the FogBugz token will be stored in your home directory, allowing pushing without a password.
If you ever need to logout of Kiln, simply run "hg logout'' list of commands:
logout log out of http repositories use "hg -v help kilnauth" to show aliases and global options gozer:~ benjamin$
That's it.
61
If your kiln site is using SSL (i.e. the clone URL starts with https:// ), you may get an error like this:
Warning: mydomain.kilnhg.com certificate not verified (check web.cacerts config setting)
If you do, see this post for the fix.
Was this article helpful?: Yes No
62
What do you do to make sure my source code is safe?
We know that hosting source code is different than hosting your FogBugz database. We host our own source code with Kiln, and we have been using Kiln internally for months.
All of your source code is stored on an isolated network that can only be accessed by the Kiln web servers. Every bit of Kiln is hosted on the same secure infrastructure as FogBugz On Demand . We will never examine the contents of your repositories unless we are diagnosing a technical problem and have already received your express permission.
All repositories are mirrored on redundant hardware in real-time. Each day we take a backup of everything, and each night we grab those backups and store them off-site. Offsite backups are maintained for 30 days. We will always take protecting your code as seriously as we do our own.
Was this article helpful?: Yes No
63
How do I start a code review?
Here's a video that we created which explains how to create code reviews in Kiln: http://www.fogcreek.com/fogbugz/Videos.html?tab=kiln&video=Pu1NmykTxWM
Was this article helpful?: Yes No
64
What is the best workflow for performing a series of code reviews?
It actually is accessible directly from Kiln—and when accessed that way, has the behavior you want. In Kiln, under the "Reviews" drop-down that's on the right side of the toolbar, you should see a list of all reviews that are opened by you or assigned to you. You do not need to make a FogBugz filter for this. This will also go directly to the review, rather than go to the FogBugz case backing the review.
The Reviews menu is globally available in Kiln, so you can use it to go directly from code review to code review. That's how I normally edit my code reviews en bulk. Like FogBugz, unread code reviews will be blue, and read ones will be purple—enforced on the server side, so that you can trust its read/unread status even as you move between machines or browsers.
We've noticed that users are not realizing that Kiln has this functionality, and will try to make the menu more obvious in upcoming versions of Kiln.
Was this article helpful?: Yes No
65
How do I add a commit to an existing code review?
NOTE: This only applies to Kiln versions lower than 2.9
Because a code review is a case, all you need to do is associate the new changeset with the review case, and then add it to the review.
There are two ways to associate a changeset with a case:
1. If you haven't already committed that changeset, simply add "Addresses review 1234" or "Bugzid:1234" to the commit message and then push it to the server. It will be automatically linked to Case 1234.
2. If you have already made the changeset, then:
1. Open it in Kiln
2. Click "Add Case Link"
3. Specify the case number for the review you wish to add, and click "Add"
Once you've associated the changeset with the review case, an "N more changeset(s) are linked to this review" message will appear at the top of the changes pane in the review UI.
1. Click "Add to this review..."
2. A changeset selection window will pop up. Make sure the changesets you want to add are selected, and click "Ok"
You're done. Kiln will update the review case to indicate that a changeset was added. This automatically notifies the person the review is assigned to (assuming that's not you, because why would we email you to tell you what you just did?).
We know that this workflow isn't perfect, and we'll be working to streamline it in upcoming versions of Kiln, but it will get the job done.
Was this article helpful?: Yes No
66
What’s with the new review system?
Kiln's old review system worked well for us, but we know that it didn't work well for a lot of our users. Kiln reviews, like FogBugz cases, could be assigned to only one person at a time, but you guys told us that having multiuser reviews was really important to you. So we went back to the drawing board, and for Kiln 2.4, came out with an entirely new way to do reviews.
So how do they work? You start the same as always: from a changeset, the history view, the incoming or outgoing pane, or anywhere else that changesets are sold, click the "New Review" button, and choose your reviewers. Your review will then be opened...but now, a single review for all reviewers, not one review per reviewer.
All participants will be notified that they have a review available. It will be listed in the
My Reviews
, and is accessible in FogBugz via the
My Kiln Reviews
filter and the reviewedby:me search axis. Reviewers are also automatically subscribed to all reviews they participate in, so if you have Kiln set to send you email, you'll get emails whenever anyone comments.
The review now proceeds as before, with one critical difference: every participant individually decides whether to approve the review. At any point, the status of each reviewer appears at the top of the case (see the above screenshot).
There are three things that can happen to a review:
1. Everyone can approve or reject the review. If this happens, the review is automatically
Approved
or
Rejected
, depending on how reviewers voted. You can then accept the verdict and close the review.
2. There can be deadlock, with some reviewers approving, some rejecting. In this case, the review may be
Abandoned
, meaning that no consensus could be reached.
3. If only some people bother weighing in, but they all agree, you can accept the current consensus of the review and close it if you don't need to wait for everyone to approve. If removing those who haven't weighed in (or, for that matter, who disagree) results in
67
consensus, the review will automatically switch to
Approved
or
Rejected
. Conversely, adding new reviewers to an alreadycompleted review will automatically reopen the review as lacking consensus.
The new system ships out today to licensed customers, and has been available on Kiln On Demand since late last week.
Was this article helpful?: Yes No
68
Kiln and Visual Studio 2008
Integrating Kiln with Visual Studio is just a matter of choosing one of the integration tools for Mercurial. Some of the recommend ones to check out are:
VisualHg from Codeplex at http://visualhg.codeplex.com/
HgSccPackage with instructions at https://bitbucket.org/zzsergant/hgsccpackage/wiki/configVS
Was this article helpful?: Yes No
69
How do I use the Electric DAG?
Kiln 2.0 brings a new feature for understanding and exploring your code's history. We call it the
Electric DAG
.
Mercurial is called a "DAG-based DVCS" because the relationship of each changeset with its parents (the changeset that it is based on) forms a directed acyclic graph . A mathematical understanding of this isn't necessary to use Kiln, of course, but the DAG nature of your repository's history exposes some interesting facts.
You can find the DAG view of your repository by clicking "History" at the top of any repository. You'll see your complete repository history, with the tip at the top. Each changeset is connected to its parent (or parents, for merges) by a colored line. By following these lines, you can trace a changeset's ancestry down the page, all the way back to the beginning of your repository. You can also trace a changeset's line up the DAG, to find what other changesets include those changes.
Of course, tracing lines on a screen isn't the easiest way to track your code's history. This is where the Electric DAG comes in. Click the background of any changeset in that list, and---zap!---the ancestors and descendants of that changeset are highlighted. Changesets that aren't related, that is, which aren't an ancestor of the selected changeset and don't descend from the selected changeset, are shown in gray. Only the bright changesets are related to the selected one.
The Electric DAG can
reveal what changes are included in a tagged changeset
, such as a specific build version. Select the tagged changeset, and look at the highlighted changes below it:
All the highlighted changesets were included in Version 1.7. Any gray changesets aren't ancestors of the changeset tagged Version-1.7.
For example, Patrick's change with the message "sort diffbookmarks() output" is included in the new version, but David's fix to "remove unused variable" isn't.
The electric DAG can also
tell you what tagged changeset a given changeset is included in
. For instance, let's select David's
"remove unused variable" changeset, which we saw didn't make it into Version 1.7:
70
Now looking at the descendants of that changeset (which are above it on the DAG), we see that the first tagged changesets that's highlighted is Version-1.7.1. So David's fix will be included in that release---go ahead and tell that frantic customer that his fix is on the way
(I'll wait here). As you expect, the Version-1.7 changeset is gray, because David's changeset wasn't included in that release.
The electric DAG has
one more trick
up its glowing blue sleeve. First, click any changeset to electrify it. Then, hold the Control (ctrl) key on your keyboard and click another changeset. Here, I've clicked the changesets tagged Version-1.7.1 and Version-1.7:
What's going on here? Kiln has highlighted all the changesets that are different between the ancestries of the two tags. In other words, every highlighted changeset is included in version 1.7.1 but not in version 1.7. The changeset we were just looking at, "remove unused variable", is highlighted, because it made the 1.7.1 release but not the 1.7 release. All the other highlighted changesets are in the same situation: ready to go for the next release.
Think how easy it would be to write release notes for 1.7.1, or for QA to know just which bugs have been fixed between releases. Wonder no more about when a vital fix was merged into the main repository, or when a customer will be able to use a new feature. Kiln's Electric
DAG leverages the power of Mercurial to delve deep into your repository's history, so you can know your code.
Was this article helpful?: Yes No
71
Kiln 2.0 Search
Indeed, there is a new search feature that's available in Kiln 2.0, and it's designed so that you can
quickly find what you're looking
for in Kiln and
navigate around your code with ease
.
There are three basic types of search results available in Kiln 2.0:
Changesets
,
Filenames
, and
Code
results.
Changesets
Kiln 2.0 gives you the ability to search through
commit messages
in a repository to find the exact changeset you're looking for. For instance, if you're looking for that changeset where you made changes to the vnode struct, you could search for vnode and you'd end up seeing something like this:
But changeset search goes even further. If we want to
narrow these results by changeset author
, say myself, I can filter by username by adding author:Andrew into my search query.
Ta-da! I've restricted my results from the first search in order to find only the changes that I've made.
But over time, there could be hundreds of changesets authored by me, and many of them could contain similar words. Thankfully, we can tell Kiln to only
look for changesets within a certain date range
. For instance, if I want to find all the builds our awesome build manager has tagged in the last two weeks, all I need to do is search "added tag" author:rock date:-2w..today
and the changes I'm looking for are right in front of me.
72
To find all changesets that are contained between two tags, search for the two tags separated by two colons , e.g. "Version_1-
0::Version_2-0" to find everything new in version 2 of your application.
Filenames
Often, you'll want to go into Kiln and look at a file's history or you'll want to view the contents of a file you don't have cloned to your computer.
File search
is meant to get you to the file you're looking for
without having to navigate the repository file tree
. If I want to doublecheck how a specific function works in our kiln Mercurial extension, searching for kiln.py
brings up the file I'm looking for. From here, I can annotate the file, view the history, or just look at the file contents. It's that simple!
Code
One of the most powerful features of Kiln Search is the ability to search for items inside your code. If you're looking for the definition of a specific function or variable, searching using the query foo or defs:foo will return the lines inside your files where foo is
defined
.
73
Likewise, a search for refs:foo will return the line of code where foo is
referenced
.
How does Kiln determine which repository to search in initially?
Kiln tries to guess which repository is most likely to have the result you're looking for based on a few factors. First, if you're already on a repository screen or have used the repository selector widgit on the search page, then Kiln will look in that repository first first. If not, Kiln looks at your
most commonly used repositories
and find the first repository with a result.
Failing both of these, Kiln will show you the
repository with the most results
.
I keep forgetting all these search axis. Is there any other way for me to use them?
Remembering the name of each search axis can be difficult, especially if you don't use Kiln search often. Although using the name of the axis in the query will be the fastest way to use an axis, the
Search Options
popup on the results page gives you a friendly interface to the same features.
Was this article helpful?: Yes No
74
Kiln 2.0: Command Line Path Guessing
You must have met an awfully smart birdie, then! Path guessing tries to remove the constant pain of either
adding a bunch of paths
to your hgrc file or
copying URLs back and forth
all day long. The incoming , outgoing , pull , and push Mercurial commands are supported for this extension.
After you install the Kiln Client, which includes the kiln extension, you should see the following section added to your Mercurial.ini
file:
[kiln_scheme] kiln=http://<yourdomain>.kilnhg.com/Repo
Path guessing uses these entries to determine the location your Kiln account. If you use
multiple Kiln installs
, path guessing will support guessing to different installs so long as they are all specified here.
After cloning a repository, I see that the only path available to me (the default path) is the repository I cloned off of, in this case my personal andrew branch of a project.
PS C:\demo> hg paths default = https://songexe.kilnhg.com/Repo/Website/2-0/andrew
Now lets say I've made some changes and want to push them out to my branch. Luckily, that's my default branch, so I can just type hg out :
PS C:\demo> hg out comparing with https://songexe.kilnhg.com/Repo/Website/2-0/andrew searching for changes changeset: 29:6951f1d98d7b tag: tip user: Andrew Song <andrew@fogcreek.com> date: Thu Aug 19 14:00:59 2010 -0400 summary: Added newfile.txt to the repository
If I just type hg push now, it'll get pushed out to my default branch:
PS C:\demo> hg push pushing to https://songexe.kilnhg.com/Repo/Website/2-0/andrew searching for changes remote: kiln: successfully pushed one changeset
Now I'd like to push this change to the parent repository. Previously, I'd have to go into Kiln and manually grab the URL for my parent.
Thankfully, we now have path guessing! By using the command hg kiln --targets or hg kiln -t for short, we can see a list of all
non-empty
repositories related to this in Kiln:
PS C:\demo> hg kiln -t
The following Kiln targets are available for this repository:
http://songexe.kilnhg.com/Repo/Website/1-0/OldWebsite
http://songexe.kilnhg.com/Repo/Website/2-0/Parent
http://songexe.kilnhg.com/Repo/Website/2-0/andrew
http://songexe.kilnhg.com/Repo/Website/2-0/david
http://songexe.kilnhg.com/Repo/Website/2-0/kareem
Now, all I need to do is
completely
and
uniquely
specify any
URL part
.
PS C:\demo> hg push Parent
75
pushing to https://songexe.kilnhg.com/Repo/Website/2-0/Parent searching for changes remote: kiln: successfully pushed one changeset
Since
Parent
was a unique part of the URL slug, path guessing knew exactly which repository I meant and pushed to it without forcing me to fumble around with URLs.
What if I had typed hg push 2-0 instead? Since this doesn't uniquely match any part of the URL, path guessing will just
display a list
of all
matching targets
:
PS C:\demo> hg push 2-0 abort: 2-0 matches more than one Kiln repository:
http://songexe.kilnhg.com/Repo/Website/2-0/Parent
http://songexe.kilnhg.com/Repo/Website/2-0/andrew
http://songexe.kilnhg.com/Repo/Website/2-0/david
http://songexe.kilnhg.com/Repo/Website/2-0/kareem
Hopefully, path guessing will improve your interaction with Kiln by
removing some inconveniences
and
streamlining your workflow
. It sure has made my life easier!
Was this article helpful?: Yes No
76
What’s new in Kiln 2.4.105?
If you're coming from the last On Demand release, then you've got two major new features:
1.
New Review System
: We've documented this elsewhere , but the review system has been entirely overhauled to focus around multiple simultaneous reviewers.
2.
Kiln Customizations
: You can now add JavaScript-based customizations to Kiln via a tool we call Glaze. We'll have full documentation on this feature available later today.
But if you're coming from a licensed release, you get
a lot more
:
1.
A totally new review UI
that should be a lot easier to work with, including threaded replies, a new control scheme, better attachments, and more. (This is in addition to the changed workflow documented above. Really, if you're coming from Kiln 2.3, you're going to be getting a massively revamped, tremendously improved review system that we think you'll really like.)
2.
Prefabricated web hooks
, so you no longer have to run a little service just for common integration points like HipChat or your continuous integration system.
3.
Support in the web UI for Mercurial bookmarks
, so you can get nice lightweight-style branching.
4.
A brand-new way to see related repositories
, making it easier than ever to keep track of everything going on in your project.
5.
Revamped integration with FogBugz
, changesets shown in-line in tthe cases that they're associated with.
6.
Vastly revamped public repositories
, making it easier than ever to share your open-source projects with the outside world.
7.
Customizable diff options
so you can ignore whitespace, change tab sizes, view diffs side-by-side, and more.
8.
A new search tool, the
::
operator
, which allows you to automatically search for a range of changesets. For example, you can do
Kiln_Release_2.3.0::Kiln_Release_2.4.0
to see all changes between Kiln 2.3.0 and 2.4.0 (assuming you have access to Kiln's source code, that is).
9.
Updated versions of the Kiln client tools
, allowing you to experience the newest versions of TortoiseHg and Mercurial.
10.
The ability to tell Kiln never to show certain files in diffs
, making it easier to focus on the importants parts of a changeset.
11.
DAG-based file histories
, so you can get a better idea what the actual history of your file was.
12.
Support for custom logos
, so you can have your own corporate brand instead of our beloved Dodo bird if you so choose.
13.
Lots more Ajaxy HTML5 goodness
, dramatically speeding up repository browsing.
And those are just the major features. There's a lot of other subtle improvements, such as the ability to jump to the DAG directly from a changeset, or the ability to open reviews from the incoming pane, or the fact that repo descriptions are now displayed in the UI to help guide your team where they should be working.
We really believe you'll love this release. It represents months of work by the Kiln team, and we're happy to finally get it into your hands.
Was this article helpful?: Yes No
77
How do I view the Annotation of a file in Kiln?
Yes, Kiln has this feature built-in.
1. In your repository, under the
Files
tab, find the file you wish to annotate and click on the file name.
2. From here, there is an
Annotate
button on the top-right of the screen. Clicking this will annotate the file you're currently browsing.
You can also use the TortoiseHg application to do this from your local machine. While currently browsing your working directory in a command prompt, type hgtk annotate <file path goes here> and it will do a much more detailed annotation.
I hope this helps -- please let us know if there's something more you'd like to see in Kiln!
Was this article helpful?: Yes No
78
How can I find out which version of Kiln I’m running?
The version information for Kiln is located in the footer at the bottom of every page.
Was this article helpful?: Yes No
79
Do I own both {my}.fogbugz.com and {my}.kilnhg.com?
That's correct!
If you have an On Demand account, your Kiln installation is available at {your}.kilnhg.com, and FogBugz is available at {your}.fogbugz.com.
They're tightly integrated and logins are hooked up to eachother, so logging into one will log you into the other, and vica-versa.
Was this article helpful?: Yes No
80
How can I easily let guests see my code?
Yep! Any of your projects in Kiln can be made "Public", so anyone can clone or pull from the repositories in that project, even if they don't have a Kiln account. You can enable public access on none, any, or all of your projects. Here's how:
1. Find the project you want to make public, then choose "Configure". On the project configuration, choose "Enable Public Access".
2. Choose "Public Access", then click OK.
3. That's it! Public projects are marked with an unlocked lock icon.
Public access is read only; only authorized users on your Kiln account, with the appropriate permissions, can push to or configure a public repository. Of course, your private projects will still be accessible only to authorized users, and you can disable public access by choosing
"Private Access" in step 2, above. We hope this feature makes it easier for you to share your open source and other public code with your users, while keeping all your code together in Kiln.
Was this article helpful?: Yes No
81
Should I use more than one repository?
The short answer:
Yes, with a DVCS, you should use at least one separate repo per project, including shared projects and libraries.
The long answer:
We had basically the same setup here at Fog Creek when we were using Subversion. One big repo for everything. When we switched over to Mercurial, we quickly learned that DVCSs don't work the same way, and aren't really suited for one large repository like that. Now we have several repositories for each project.
For example, with Copilot , we have several different moving parts that are relatively independent of each other:
Helpers (downloadable EXE clients)
Reflector (server that links communication between helpers)
Website
Billing System
Aardvark (shared library used by the reflector, website, and billing system)
For each of those parts, we've created a separate repository group and we keep a devel and stable repository in each of those groups. New features go into devel and eventually get merged forward to stable , while bug fixes go into stable and get merged back into devel .
To keep everything in sync for deploy, we use tags. In Subversion, tags are a pain because they're really not a tag as much as they are a full copy of your code in a different directory. With Mercurial, a tag is more like meta data on the repository, and you just treat them like a version number.
So let's say I need to deploy a new version of the Copilot website. To do it, I'll need a copy of website-stable and a copy of aardvark-stable . First, I tag each of those repos on my local machine (we have a batch file that does it for us, calculating out the tag number, e.g. Website000123 ). Then we kick off the build process with our tag, which clones both repos from the server into a build directory and runs hg up -C Website000123 to update them to the tag. Then it builds and deploys.
If I ever need to go back in time to that particular build, I can just run the same command, hg up -C Website000123 in each repo.
You should notice that we tag both the Website and the Aardvark repos with Website000123 , instead of tagging Aardvark with
Aardvark000123 . This is because we'll also be tagging Aardvark for our reflector builds ( Reflector000456 ) when they go out, and we want to be able to know which was which.
We're currently working on some in-depth tutorials on exactly these sorts of topics. In the meantime, the following SE pages are a good start on some of the repo management topics I've mentioned here:
What are best practices for managing pushing and pulling a branch repo to/from its parent?
Kiln Branch and Merge How-To
Update:
The long-promised tutorial is out! Check it out HgInit.com
Was this article helpful?: Yes No
82
Can I control Kiln’s display of diffs and files?
We sure do! As of Kiln 2.4, every diff and file view lets you customize the display to your liking. When viewing a file, click the gear in the top-right corner; on a diff or in a code review, click the gear in any diff's header:
All displayed files and diffs have two configuration options:
visible whitespace
and
tab size
. Enable "Show whitespace" to add subtle markers for tabs and spaces in your code.
Spaces are marked with a dot, while tabs are a small arrow, so you can easily spot inconsistent whitespace. If you don't like the default 8space tabs, change "spaces per tab" to your preferred size. See the result in this Makefile:
In addition to these options, diffs have two additional customizations. Choose to
ignore whitespace changes
to only show the changes made to visible characters. Let's take as an example changeset 0c84afa1d622 from Mercurial itself . The standard diff for this change looks complicated:
83
However, ignoring whitespace changes simplifies things, and reveals what the diff actually changed:
If you're often reformatting code, this display can be a lifesaver. This option is equivalent to the -w / --ignore-all-space flag at the
Mercurial command line.
The second option for diff display changes from a standard,
stacked diff
to a
side-by-side diff
. You might be familar with this style from kdiff3 or other visual diff tools. Rather than showing removed and added lines interleaved in a single column,
side-by-side diffs
show removed lines on the left and added lines on the right: becomes
84
Compare each line's changes directly across the screen. These new options allow you to customize Kiln's display of your code to your liking. I love to tweak my workspace, and these options make it easy to get Kiln working just right for me.
Was this article helpful?: Yes No
85
