Commits

Steve Losh committed 29e21cd

Add a lot of documentation.

Comments (0)

Files changed (2)

+-*- markdown -*-
+
+hg-paste
+========
+
+hg-paste adds an `hg paste` command to Mercurial which can send diffs to various pastebin websites for easy sharing.
+
+It was inspired by [Pocoo][]'s [hgpaste][pocoopaste] extension, but is designed to work with public pastebin websites instead of private installations of [LodgeIt][].
+
+[Pocoo]: http://www.pocoo.org/
+[pocoopaste]: http://dev.pocoo.org/hg/hgpaste/
+[LodgeIt]: http://dev.pocoo.org/projects/lodgeit/
+
+Installing
+----------
+
+Clone the repository:
+
+    hg clone http://bitbucket.org/sjl/hg-paste/
+
+Edit the `[extensions]` section in your `~/.hgrc` file:
+
+    [extensions]
+    paste = (path to)/hg-paste/paste.py
+
+Using the Command
+-----------------
+
+To paste a diff of all uncommitted changes in the working directory:
+
+    hg paste
+
+To paste the changes that revision `REV` made:
+
+    hg paste -r REV
+
+To paste the changes between revisions `REV1` and `REV2`:
+
+    hg paste -r REV1:REV2
+
+If any files are specified only those files will be included in the diffs.
+
+Several options can be used to specify more metadata about the paste:
+
+    hg paste --user Steve --title 'Progress on feature X' --keep
+
+The pastebin website to use can be specified with `--dest`, but currently
+only [dpaste](http://dpaste.com/) is supported.
+
+Questions, Comments, Suggestions
+--------------------------------
+
+If you find any bugs, please create an issue in the [issue tracker][issues].
+
+If you want to contribute (support for more pastebin websites would be great), fork the [repository][] on BitBucket and send a pull request.
+
+[repository]: http://bitbucket.org/sjl/hg-paste
 #!/usr/bin/env python
 
-'''send information from Mercurial to various pastebin websites
+'''send diffs from Mercurial to various pastebin websites
 '''
 
 import urllib2
     location = response.geturl()
     return location
 
+
 pastebins = {
     'dpaste': { 'url': 'http://dpaste.com/api/v1/',
                 'parameters': {
 }
 
 def paste(ui, repo, *fnames, **opts):
+    '''send diffs from Mercurial to various pastebin websites
+    
+    Send a diff of the specified files to a pastebin website to easily
+    share with other people.  If no files are specified all files will
+    be included.
+    
+    To paste a diff of all uncommitted changes in the working directory:
+    
+        hg paste
+    
+    To paste the changes that revision REV made:
+    
+        hg paste -r REV
+    
+    To paste the changes between revisions REV1 and REV2:
+    
+        hg paste -r REV1:REV2
+    
+    Several options can be used to specify more metadata about the paste:
+    
+        hg paste --user Steve --title 'Progress on feature X' --keep
+    
+    The pastebin website to use can be specified with --dest, but currently
+    only dpaste (http://dpaste.com/) is supported.
+    
+    '''
     dest = opts.pop('dest')
     dry = opts.pop('dry_run')
     if not dest:
     
     dpaste
         website: http://dpaste.com/
-        supported options: --title, --keep, --user
+        supported metadata options: --title, --keep, --user
     ''')),
 )