/README.txt

 1About
 2=====
 3hgkeychain is an extension for mercurial that lets the user use the MacOS X keychain to store passwords for remote repositories.
 4
 5Requirements
 6============
 7Mac OS X 10.5+ (should work on older OSes but only tested on 10.5 and 10.6)
 8Python 2.5 (should work on older versions of Python but only tested on 2.5 and 2.6)
 9Mercurial 0.9+ (works on 1.0 through 1.3)
10My pykeychain Python Module
11
12Installation
13============
14The easiest way to install hgkeychain is to use easy_install or pip:
15
16	sudo easy_install -U pykeychain
17
18(The sudo command may be optional depending on your machine's set up)
19
20Activation
21==========
22Edit your ~/.hgrc file to activate the extension:
23
24	[extensions]
25	hgkeychain=
26
27See http://www.selenic.com/mercurial/wiki/index.cgi/UsingExtensions for more information on installing and activating mercurial extensions.
28
29Usage
30=====
31Once properly installed and activated hgkeychain will allow mercurial to store and retrieve repository passwords using the user's keychain.
32
33You should generally embed the remote repository's username in the repository URL when performing a clone, push or pull operation. E.g.:
34
35	http://username@example.com/hg/repository
36
37If you try to clone, push or pull to a password protected repository mercurial will query the user's Keychain for the repository password. If no password is found, mercurial will prompt the user for the password (via the terminal) and then store the password in the Keychain.
38
39Configuration
40=============
41hgkeychain is aware of [auth] settings in your ~/.hgrc.  For example, if you have a BitBucket account, you could set this up as such:
42
43  [auth]
44  bb.prefix = bitbucket.org/
45  bb.username = {username}
46  bb.schemes =  http https
47
48The prefix is used to store your password in keychain, so all repositories with the same prefix will share the same keychain item.  This keeps your keychain from getting cluttered up with a single keychain item per repository.  Note that [auth] requires at least Mercurial verion 1.3.  The old URL replacement regular expressions have been removed in support of [auth].
49
50You can turn on logging to help debug problems like so:
51
52  [hgkeychain]
53  logging=1