gollum 2.4.11 → 2.4.12

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    Y2E5MTY1MjYwYjk5ZjQyZTBkMTM4N2FjNWI2YzIwNDEyZDJjOTlkYw==
+  data.tar.gz: !binary |-
+    NTljMWE0NzZkZDhiOWU4N2Y5NDM3ZDY5MjUyMTBkNjE3MzI4NDllNQ==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    MDUwYWRjMDM2MGZiYjliZDQ4OGZkZmM2ZWFkYjE0OTk5NWE5NmM3MjkzZTg2
+    ZWJhODc2MThiZWE4OTZiN2U5MjJjYWQwMjQ0Y2FhMWFiOGRkZTY5MDA3Y2Y0
+    NTk3MjQzY2U3ZDI5NDBiMmQxOGJmM2ViM2YzNWY0ZjAxMDBkNzc=
+  data.tar.gz: !binary |-
+    NzZiMjFiOTg0MTViMDI3MWQ4Zjk2MDg3MWZhZWZjYTU0ZmE3ZjM2YjE2YTE4
+    M2UxZTY4ZTBmYjMxZmZmZThkZGFlN2YxNWQ5ZjJmYjVkYjdkMGRiOTZmY2I2
+    OWVlYTllODI3MzYzYmZhZGEzNDJiYWM0ZjA1Y2RiYzI3ZTljNTA=

data/Gemfile

@@ -1,4 +1,4 @@
 source 'https://rubygems.org'
 
 gemspec
-gem 'rake', '~> 10.0.2'
+gem 'rake', '~> 10.0.3'

data/HISTORY.md

@@ -1,3 +1,7 @@
+# 2.4.11 / 2013-01-08
+
+* Numerous security issues have been fixed. Please update to `2.4.11`
+
 # 1.4.0 / 2012-04-10
 
 * Minor

data/README.md

@@ -1,8 +1,8 @@
 gollum -- A wiki built on top of Git
 ====================================
 
-[![Build Status](https://secure.travis-ci.org/github/gollum.png?branch=master)](http://travis-ci.org/github/gollum)
-[![Dependency Status](https://gemnasium.com/github/gollum.png)](https://gemnasium.com/github/gollum)
+[![Build Status](https://secure.travis-ci.org/gollum/gollum.png?branch=master)](http://travis-ci.org/gollum/gollum)
+[![Dependency Status](https://gemnasium.com/gollum/gollum.png)](https://gemnasium.com/gollum/gollum)
 
 ## DESCRIPTION
 
@@ -20,21 +20,31 @@ Gollum follows the rules of [Semantic Versioning](http://semver.org/) and uses
 [TomDoc](http://tomdoc.org/) for inline documentation.
 
 ## SYSTEM REQUIREMENTS
+
 - Python 2.5+ (2.7.3 recommended)
 - Ruby 1.8.7+ (1.9.3 recommended)
 - Unix like operating system (OS X, Ubuntu, Debian, and more)
 - Will not work on Windows (because of [grit](https://github.com/github/grit))
 
+## SECURITY
+
+Don't enable `--custom-css` or `--custom-js` unless you trust every user who has the ability to edit the wiki.
+A better solution with more security is being tracked in [#665](https://github.com/gollum/gollum/issues/665).
+
 ## INSTALLATION
 
 The best way to install Gollum is with RubyGems:
 
-    $ [sudo] gem install gollum
+```bash
+$ [sudo] gem install gollum
+```
 
 If you're installing from source, you can use [Bundler][bundler] to pick up all the
 gems:
 
-    $ bundle install
+```bash
+$ bundle install
+```
 
 In order to use the various formats that Gollum supports, you will need to
 separately install the necessary dependencies for each format. You only need
@@ -43,7 +53,7 @@ to install the dependencies for the formats that you plan to use.
 * [ASCIIDoc](http://www.methods.co.nz/asciidoc/) -- `brew install asciidoc` on mac or `apt-get install -y asciidoc` on Ubuntu
 * [Creole](http://wikicreole.org/) -- `gem install creole`
 * [Markdown](http://daringfireball.net/projects/markdown/) -- `gem install redcarpet`
-* [GitHub Flavored Markdown](http://github.github.com/github-flavored-markdown/) -- `gem install github-markdown`
+* [GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown) -- `gem install github-markdown`
 * [Org](http://orgmode.org/) -- `gem install org-ruby`
 * [Pod](http://search.cpan.org/dist/perl/pod/perlpod.pod) -- `Pod::Simple::HTML` comes with Perl >= 5.10. Lower versions should install Pod::Simple from CPAN.
 * [RDoc](http://rdoc.sourceforge.net/)
@@ -59,13 +69,17 @@ To view and edit your Gollum repository locally via the built in web
 interface, simply install the Gollum gem, navigate to your repository via the
 command line, and run the executable:
 
-    $ gollum
+```bash
+$ gollum
+```
 
 This will start up a web server running the Gollum frontend and you can view
 and edit your wiki at http://localhost:4567. To get help on the command line
 utility, you can run it like so:
 
-    $ gollum --help
+```bash
+$ gollum --help
+```
 
 Note that the gollum server will not run on Windows because of [an issue](https://github.com/rtomayko/posix-spawn/issues/9) with posix-spawn (which is used by Grit).
 
@@ -76,12 +90,11 @@ is written in `page files` and may be organized into directories any way you
 choose. Special footers can be created in `footer files`. Other content
 (images, PDFs, etc) may also be present and organized in the same way.
 
-
 ## PAGE FILES
 
 Page files may be written in any format supported by
-[GitHub-Markup](http://github.com/github/markup) (except roff). The
-current list of formats and allowed extensions is:
+[GitHub-Markup](http://github.com/github/markup) (except roff). By default,
+Gollum recognizes the following extensions:
 
 * ASCIIDoc: .asciidoc
 * Creole: .creole
@@ -93,8 +106,16 @@ current list of formats and allowed extensions is:
 * Textile: .textile
 * MediaWiki: .mediawiki, .wiki
 
+You may also register your own extensions and parsers:
+
+```ruby
+Gollum::Markup.register(:angry, "Angry") do |content|
+  content.upcase
+end
+```
+
 Gollum detects the page file format via the extension, so files must have one
-of the supported extensions in order to be converted.
+of the default or registered extensions in order to be converted.
 
 Page file names may contain any printable UTF-8 character except space
 (U+0020) and forward slash (U+002F). If you commit a page file with any of
@@ -110,7 +131,7 @@ automatically generated table of contents will be shown instead.
 
 ## SIDEBAR FILES
 
-Sidebar files allow you to add a simple sidebar to your wiki.  Sidebar files
+Sidebar files allow you to add a simple sidebar to your wiki. Sidebar files
 are named `_Sidebar.ext` where the extension is one of the supported formats.
 Sidebars affect all pages in their directory and any subdirectories that do not
 have a sidebar file of their own.
@@ -138,11 +159,14 @@ allowed.
 
 ## TITLES
 
-The first defined `h1` will override the default header on a page. There are two ways to set a page title. The metadata syntax:
+The first defined `h1` will override the default header on a page. There are
+two ways to set a page title. The metadata syntax:
+
+    <!-- --- title: New Title -->
 
-`<!-- --- title: New Title -->`
+The first `h1` tag can be set to always override the page title, without
+needing to use the metadata syntax. Start gollum with the `--h1-title` flag.
 
-The first `h1` tag can be set to always override the page title, without needing to use the metadata syntax. Start gollum with the `--h1-title` flag.
 ## BRACKET TAGS
 
 A variety of Gollum tags use a double bracket syntax. For example:
@@ -174,8 +198,8 @@ The above tag will create a link to the corresponding page file named
 `Frodo-Baggins.ext` where `ext` may be any of the allowed extension types. The
 conversion is as follows:
 
-  1. Replace any spaces (U+0020) with dashes (U+002D)
-  2. Replace any slashes (U+002F) with dashes (U+002D)
+1. Replace any spaces (U+0020) with dashes (U+002D)
+2. Replace any slashes (U+002F) with dashes (U+002D)
 
 If you'd like the link text to be something that doesn't map directly to the
 page name, you can specify the actual page name after a pipe:
@@ -278,6 +302,12 @@ specified, default alignment is `left`.
 
     [[gollum.png|float]]
 
+By default text will fill up all the space around the image. To control how
+much should show up use this tag to stop and start a new block so that
+additional content doesn't fill in.
+
+    [[_]]
+
 To specify a max-width, use the `width=` option. Units must be specified in
 either `px` or `em`.
 
@@ -318,7 +348,9 @@ The `:universal_toc` is not enabled by default.  To set the option,
 add the option to the `:wiki_options` hash before starting the
 frontend app:
 
-    Precious::App.set(:wiki_options, {:universal_toc => true})
+```ruby
+Precious::App.set(:wiki_options, {:universal_toc => true})
+```
 
 ## SYNTAX HIGHLIGHTING
 
@@ -352,9 +384,9 @@ As an extra feature, you can syntax highlight a file from your repository, allow
 you keep some of your sample code in the main repository. The code-snippet is
 updated when the wiki is rebuilt. You include github code like this:
 
-    ```html:github/gollum/master/test/file_view/1_file.txt```
+    ```html:github:gollum/gollum/master/test/file_view/1_file.txt```
 
-This will make the builder look at the **github user**, in the **gollum project**,
+This will make the builder look at the **gollum user**, in the **gollum project**,
 in the **master branch**, at path **test/file_view/1_file.txt**. It will be
 rewritten to:
 
@@ -364,7 +396,7 @@ rewritten to:
     </ol>
     ```
 
-Which will be parsed as HTML code during the Pygments run, and thereby coloured 
+Which will be parsed as HTML code during the Pygments run, and thereby coloured
 appropriately.
 
 ## MATHEMATICAL EQUATIONS
@@ -373,13 +405,12 @@ Start gollum with the `--mathjax` flag. Read more about [MathJax](http://docs.ma
 
 Inline math:
 
-- $2^2$
-- `\\(2^2\\)`
+- \\(2^2\\)
 
 Display math:
 
 - $$2^2$$
-- [2^2]
+- \\[2^2\\]
 
 ## SEQUENCE DIAGRAMS
 
@@ -396,31 +427,36 @@ You can replace the string "blue-modern" with any supported style.
 
 ## API DOCUMENTATION
 
-The Gollum API allows you to retrieve raw or formatted wiki content from a Git
-repository, write new content to the repository, and collect various meta data
-about the wiki as a whole.
+The [Gollum API](https://github.com/gollum/gollum-lib/) allows you to retrieve
+raw or formatted wiki content from a Git repository, write new content to the
+repository, and collect various meta data about the wiki as a whole.
 
-Initialize the Gollum::Repo object:
+Initialize the `Gollum::Repo` object:
 
-    # Require rubygems if necessary
-    require 'rubygems'
+```ruby
+# Require rubygems if necessary
+require 'rubygems'
 
-    # Require the Gollum library
-    require 'gollum'
+# Require the Gollum library
+require 'gollum-lib'
 
-    # Create a new Gollum::Wiki object by initializing it with the path to the
-    # Git repository.
-    wiki = Gollum::Wiki.new("my-gollum-repo.git")
-    # => <Gollum::Wiki>
+# Create a new Gollum::Wiki object by initializing it with the path to the
+# Git repository.
+wiki = Gollum::Wiki.new("my-gollum-repo.git")
+# => <Gollum::Wiki>
+```
 
-By default, internal wiki links are all absolute from the root. To specify a different base path, you can specify the `:base_path` option:
+By default, internal wiki links are all absolute from the root. To specify a different
+base path, you can specify the `:base_path` option:
 
-    wiki = Gollum::Wiki.new("my-gollum-repo.git", :base_path => "/wiki")
+```ruby
+wiki = Gollum::Wiki.new("my-gollum-repo.git", :base_path => "/wiki")
+```
 
 Note that base_path just modifies the links. To map gollum to a non-root location:
 
 - Use the gollum binary: `gollum path/to/wiki --base-path mywiki`
-- Define config.ru with `map`. See [#532](https://github.com/github/gollum/issues/532) for an example.
+- Define config.ru with `map`. See [#532](https://github.com/gollum/gollum/issues/532) for an example.
 
 > :base_path     - String base path for all Wiki links.
 >
@@ -430,92 +466,116 @@ Note that base_path just modifies the links. To map gollum to a non-root locatio
 
 Get the latest version of the given human or canonical page name:
 
-    page = wiki.page('page-name')
-    # => <Gollum::Page>
+```ruby
+page = wiki.page('page-name')
+# => <Gollum::Page>
 
-    page.raw_data
-    # => "# My wiki page"
+page.raw_data
+# => "# My wiki page"
 
-    page.formatted_data
-    # => "<h1>My wiki page</h1>"
+page.formatted_data
+# => "<h1>My wiki page</h1>"
 
-    page.format
-    # => :markdown
+page.format
+# => :markdown
 
-    vsn = page.version
-    # => <Grit::Commit>
+vsn = page.version
+# => <Grit::Commit>
 
-    vsn.id
-    # => '3ca43e12377ea1e32ea5c9ce5992ec8bf266e3e5'
+vsn.id
+# => '3ca43e12377ea1e32ea5c9ce5992ec8bf266e3e5'
+```
 
 Get the footer (if any) for a given page:
 
-    page.footer
-    # => <Gollum::Page>
-    
+```ruby
+page.footer
+# => <Gollum::Page>
+```
+
 Get the header (if any) for a given page:
 
-    page.header
-    # => <Gollum::Page>
+```ruby
+page.header
+# => <Gollum::Page>
+```
 
 Get a list of versions for a given page:
 
-    vsns = wiki.page('page-name').versions
-    # => [<Grit::Commit, <Grit::Commit, <Grit::Commit>]
+```ruby
+vsns = wiki.page('page-name').versions
+# => [<Grit::Commit, <Grit::Commit, <Grit::Commit>]
 
-    vsns.first.id
-    # => '3ca43e12377ea1e32ea5c9ce5992ec8bf266e3e5'
+vsns.first.id
+# => '3ca43e12377ea1e32ea5c9ce5992ec8bf266e3e5'
 
-    vsns.first.authored_date
-    # => Sun Mar 28 19:11:21 -0700 2010
+vsns.first.authored_date
+# => Sun Mar 28 19:11:21 -0700 2010
+```
 
 Get a specific version of a given canonical page file:
 
-    wiki.page('page-name', '5ec521178e0eec4dc39741a8978a2ba6616d0f0a')
+```ruby
+wiki.page('page-name', '5ec521178e0eec4dc39741a8978a2ba6616d0f0a')
+```
 
 Get the latest version of a given static file:
 
-    file = wiki.file('asset.js')
-    # => <Gollum::File>
+```ruby
+file = wiki.file('asset.js')
+# => <Gollum::File>
 
-    file.raw_data
-    # => "alert('hello');"
+file.raw_data
+# => "alert('hello');"
 
-    file.version
-    # => <Grit::Commit>
+file.version
+# => <Grit::Commit>
+```
 
 Get a specific version of a given static file:
 
-    wiki.file('asset.js', '5ec521178e0eec4dc39741a8978a2ba6616d0f0a')
+```ruby
+wiki.file('asset.js', '5ec521178e0eec4dc39741a8978a2ba6616d0f0a')
+```
 
 Get an in-memory Page preview (useful for generating previews for web
 interfaces):
 
-    preview = wiki.preview_page("My Page", "# Contents", :markdown)
-    preview.formatted_data
-    # => "<h1>Contents</h1>"
+```ruby
+preview = wiki.preview_page("My Page", "# Contents", :markdown)
+preview.formatted_data
+# => "<h1>Contents</h1>"
+```
 
 Methods that write to the repository require a Hash of commit data that takes
 the following form:
 
-    commit = { :message => 'commit message',
-               :name => 'Tom Preston-Werner',
-               :email => 'tom@github.com' }
+```ruby
+commit = { :message => 'commit message',
+           :name => 'Tom Preston-Werner',
+           :email => 'tom@github.com' }
+```
 
 Write a new version of a page (the file will be created if it does not already
 exist) and commit the change. The file will be written at the repo root.
 
-    wiki.write_page('Page Name', :markdown, 'Page contents', commit)
+```ruby
+wiki.write_page('Page Name', :markdown, 'Page contents', commit)
+```
 
 Update an existing page. If the format is different than the page's current
 format, the file name will be changed to reflect the new format.
 
-    page = wiki.page('Page Name')
-    wiki.update_page(page, page.name, page.format, 'Page contents', commit)
+```ruby
+page = wiki.page('Page Name')
+wiki.update_page(page, page.name, page.format, 'Page contents', commit)
+```
 
 To delete a page and commit the change:
 
-    wiki.delete_page(page, commit)
+```ruby
+wiki.delete_page(page, commit)
+```
 
 ### RACK
 
@@ -523,38 +583,39 @@ You can also run gollum with any rack-compatible server by placing this config.r
 file inside your wiki repository. This allows you to utilize any Rack middleware
 like Rack::Auth, OmniAuth, etc.
 
-    #!/usr/bin/env ruby
-    require 'rubygems'
-    require 'gollum/frontend/app'
+```ruby
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'gollum/app'
 
-    gollum_path = File.expand_path(File.dirname(__FILE__)) # CHANGE THIS TO POINT TO YOUR OWN WIKI REPO
-    Precious::App.set(:gollum_path, gollum_path)
-    Precious::App.set(:default_markup, :markdown) # set your favorite markup language
-    Precious::App.set(:wiki_options, {:universal_toc => false})
-    run Precious::App
+gollum_path = File.expand_path(File.dirname(__FILE__)) # CHANGE THIS TO POINT TO YOUR OWN WIKI REPO
+Precious::App.set(:gollum_path, gollum_path)
+Precious::App.set(:default_markup, :markdown) # set your favorite markup language
+Precious::App.set(:wiki_options, {:universal_toc => false})
+run Precious::App
+```
 
 Your Rack middleware can pass author details to Gollum in a Hash in the session under the 'gollum.author' key.
 
 ## WINDOWS FILENAME VALIDATION
+
 Note that filenames on windows must not contain any of the following characters `\ / : * ? " < > |`. See [this support article](http://support.microsoft.com/kb/177506) for details.
 
 ## CONFIG FILE
 
-Gollum optionally takes a `--config file`. See [config.rb](https://github.com/github/gollum/blob/master/config.rb) for an example.
+Gollum optionally takes a `--config file`. See [config.rb](https://github.com/gollum/gollum/blob/master/config.rb) for an example.
 
-## CUSTOM CSS
+## CUSTOM CSS/JS
 
-The `--css` flag will inject `custom.css` from the root of your git repository into each page. `custom.css` must be commited to git or you will get a 302 redirect to the create page. Here's an example of floating the sidebar to the left.
+The `--css` flag will inject `custom.css` from the root of your git repository into each page. `custom.css` must be commited to git or you will get a 302 redirect to the create page.
 
-```css
-#wiki-rightbar { float: left !important; }
-```
+The `--js` flag will inject `custom.js` from the root of your git repository into each page. `custom.js` must be commited to git or you will get a 302 redirect to the create page.
 
 ## CONTRIBUTE
 
-If you'd like to hack on Gollum, start by forking my repo on GitHub:
+If you'd like to hack on Gollum, start by forking the repo on GitHub:
 
-http://github.com/github/gollum
+http://github.com/gollum/gollum
 
 To get all of the dependencies, install the gem first. The best way to get
 your changes merged back into core is as follows:
@@ -567,23 +628,57 @@ your changes merged back into core is as follows:
 1. Do not change the version number, I will do that on my end
 1. If necessary, rebase your commits into logical chunks, without errors
 1. Push the branch up to GitHub
-1. Send a pull request to the github/gollum project.
+1. Send a pull request to the gollum/gollum project.
 
 ## RELEASING
+
+Gollum uses [Semantic Versioning](http://semver.org/).
+
     x.y.z
 
-    For z releases:
-    $ rake bump
-    $ rake release
+For z releases:
+
+```bash
+$ rake bump
+$ rake release
+```
+
+For x.y releases:
+
+```bash
+Update VERSION in lib/gollum.rb
+$ rake gemspec
+$ rake release
+```
 
-    For x.y releases:
-    Update VERSION in lib/gollum.rb
-    $ rake gemspec
-    $ rake release
-    
 ## BUILDING THE GEM FROM MASTER
-    $ gem uninstall -aIx gollum
-    $ git clone https://github.com/github/gollum.git
-    $ cd gollum
-    gollum$ rake build
-    gollum$ gem install --no-ri --no-rdoc pkg/gollum*.gem
+
+```bash
+$ gem uninstall -aIx gollum
+$ git clone https://github.com/gollum/gollum.git
+$ cd gollum
+gollum$ rake build
+gollum$ gem install --no-ri --no-rdoc pkg/gollum*.gem
+```
+
+## RUN THE TESTS
+
+```bash
+$ bundle install
+$ bundle exec rake test
+```
+
+## WORK WITH TEST REPOS
+
+An example of how to add a test file to the bare repository lotr.git.
+
+```bash
+$ mkdir tmp; cd tmp
+$ git clone ../lotr.git/ .
+Cloning into '.'...
+done.
+$ git log
+$ echo "test" > test.md
+$ git add . ; git commit -am "Add test"
+$ git push ../lotr.git/ master
+```