Class: Gollum::Wiki

Inherits:
Object
  • Object
show all
Includes:
Pagination
Defined in:
lib/gollum/wiki.rb

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Pagination

included, #log_pagination_options, #page_to_skip

Constructor Details

#initialize(path, options = {}) ⇒ Wiki

Public: Initialize a new Gollum Repo.

path - The String path to the Git repository that holds the Gollum

site.

options - Optional Hash:

:base_path     - String base path for all Wiki links.
                 Default: "/"
:page_class    - The page Class. Default: Gollum::Page
:file_class    - The file Class. Default: Gollum::File
:markup_classes - A hash containing the markup Classes for each
                  document type. Default: { Gollum::Markup }
:sanitization  - An instance of Sanitization.
:page_file_dir - String the directory in which all page files reside
:ref - String the repository ref to retrieve pages from
:ws_subs       - Array of chars to sub for ws in filenames.

Returns a fresh Gollum::Repo.



148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/gollum/wiki.rb', line 148

def initialize(path, options = {})
  if path.is_a?(GitAccess)
    options[:access] = path
    path             = path.path
  end
  @path          = path
  @page_file_dir = options[:page_file_dir]
  @access        = options[:access]       || GitAccess.new(path, @page_file_dir)
  @base_path     = options[:base_path]    || "/"
  @page_class    = options[:page_class]   || self.class.page_class
  @file_class    = options[:file_class]   || self.class.file_class
  @markup_classes = options[:markup_classes] || self.class.markup_classes
  @repo          = @access.repo
  @ref           = options[:ref] || self.class.default_ref
  @sanitization  = options[:sanitization] || self.class.sanitization
  @ws_subs       = options[:ws_subs] ||
    self.class.default_ws_subs
  @history_sanitization = options[:history_sanitization] ||
    self.class.history_sanitization
end

Class Attribute Details

.default_committer_email ⇒ Object

Sets the default email for commits.



22
23
24
 
# File 'lib/gollum/wiki.rb', line 22

def default_committer_email
  @default_committer_email
end

.default_committer_name ⇒ Object

Sets the default name for commits.



19
20
21
 
# File 'lib/gollum/wiki.rb', line 19

def default_committer_name
  @default_committer_name
end

.default_ref ⇒ Object

Sets the default ref for the wiki.



16
17
18
 
# File 'lib/gollum/wiki.rb', line 16

def default_ref
  @default_ref
end

.default_ws_subs ⇒ Object

Array of chars to substitute whitespace for when trying to locate file in git repo.



25
26
27
 
# File 'lib/gollum/wiki.rb', line 25

def default_ws_subs
  @default_ws_subs
end

.file_class ⇒ Object

Gets the file class used by all instances of this Wiki. Default: Gollum::File.



48
49
50
51
52
53
54
55
 
# File 'lib/gollum/wiki.rb', line 48

def file_class
  @file_class ||
    if superclass.respond_to?(:file_class)
      superclass.file_class
    else
      ::Gollum::File
    end
end

.history_sanitization ⇒ Object

Gets the default sanitization options for older page revisions used by instances of this Wiki.



95
96
97
98
99
100
101
102
 
# File 'lib/gollum/wiki.rb', line 95

def history_sanitization
  if @history_sanitization.nil?
    @history_sanitization = sanitization ?
      sanitization.history_sanitization  :
      false
  end
  @history_sanitization
end

.markup_classes ⇒ Object

Gets the markup class used by all instances of this Wiki. Default: Gollum::Markup



59
60
61
62
63
64
65
66
 
# File 'lib/gollum/wiki.rb', line 59

def markup_classes
  @markup_classes ||=
    if superclass.respond_to?(:markup_classes)
      superclass.markup_classes
    else
      Hash.new(::Gollum::Markup)
    end
end

.page_class ⇒ Object

Gets the page class used by all instances of this Wiki. Default: Gollum::Page.



37
38
39
40
41
42
43
44
 
# File 'lib/gollum/wiki.rb', line 37

def page_class
  @page_class ||
    if superclass.respond_to?(:page_class)
      superclass.page_class
    else
      ::Gollum::Page
    end
end

.sanitization ⇒ Object

Gets the default sanitization options for current pages used by instances of this Wiki.



86
87
88
89
90
91
 
# File 'lib/gollum/wiki.rb', line 86

def sanitization
  if @sanitization.nil?
    @sanitization = Sanitization.new
  end
  @sanitization
end

Instance Attribute Details

#base_path ⇒ Object (readonly)

The String base path to prefix to internal links. For example, when set to “/wiki”, the page “Hobbit” will be linked as “/wiki/Hobbit”. Defaults to “/”.



114
115
116
 
# File 'lib/gollum/wiki.rb', line 114

def base_path
  @base_path
end

#file_class ⇒ Object (readonly)

Gets the file class used by all instances of this Wiki.



525
526
527
 
# File 'lib/gollum/wiki.rb', line 525

def file_class
  @file_class
end

#history_sanitization ⇒ Object (readonly)

Gets the sanitization options for older page revisions used by this Wiki.



120
121
122
 
# File 'lib/gollum/wiki.rb', line 120

def history_sanitization
  @history_sanitization
end

#markup_classes ⇒ Object (readonly)

Gets the markup class used by all instances of this Wiki.



528
529
530
 
# File 'lib/gollum/wiki.rb', line 528

def markup_classes
  @markup_classes
end

#page_class ⇒ Object (readonly)

Gets the page class used by all instances of this Wiki.



522
523
524
 
# File 'lib/gollum/wiki.rb', line 522

def page_class
  @page_class
end

#page_file_dir ⇒ Object (readonly)

Gets the String directory in which all page files reside.



126
127
128
 
# File 'lib/gollum/wiki.rb', line 126

def page_file_dir
  @page_file_dir
end

#path ⇒ Object (readonly)

The String path to the Git repository that holds the Gollum site.

Returns the String path.



519
520
521
 
# File 'lib/gollum/wiki.rb', line 519

def path
  @path
end

#ref ⇒ Object (readonly)

Gets the String ref in which all page files reside.



123
124
125
 
# File 'lib/gollum/wiki.rb', line 123

def ref
  @ref
end

#repo ⇒ Object (readonly)

The Grit::Repo associated with the wiki.

Returns the Grit::Repo.



514
515
516
 
# File 'lib/gollum/wiki.rb', line 514

def repo
  @repo
end

#sanitization ⇒ Object (readonly)

Gets the sanitization options for current pages used by this Wiki.



117
118
119
 
# File 'lib/gollum/wiki.rb', line 117

def sanitization
  @sanitization
end

#ws_subs ⇒ Object (readonly)

Gets the Array of chars to sub for ws in filenames.



129
130
131
 
# File 'lib/gollum/wiki.rb', line 129

def ws_subs
  @ws_subs
end

Class Method Details

.markup_class(language = :default) ⇒ Object Also known as: default_markup_class

Gets the default markup class used by all instances of this Wiki. Kept for backwards compatibility until Gollum v2.x



70
71
72
 
# File 'lib/gollum/wiki.rb', line 70

def markup_class(language=:default)
  markup_classes[language]
end

.markup_class=(default) ⇒ Object Also known as: default_markup_class=

Sets the default markup class used by all instances of this Wiki. Kept for backwards compatibility until Gollum v2.x



76
77
78
79
 
# File 'lib/gollum/wiki.rb', line 76

def markup_class=(default)
  @markup_classes = Hash.new(default).update(markup_classes)
  default
end

Instance Method Details

#clear_cache ⇒ Object

Public: Refreshes just the cached Git reference data. This should be called after every Gollum update.

Returns nothing.



481
482
483
 
# File 'lib/gollum/wiki.rb', line 481

def clear_cache
  @access.refresh
end

#commit_for(ref) ⇒ Object

Gets the commit object for the given ref or sha.

ref - A string ref or SHA pointing to a valid commit.

Returns a Grit::Commit instance.



615
616
617
618
 
# File 'lib/gollum/wiki.rb', line 615

def commit_for(ref)
  @access.commit(ref)
rescue Grit::GitRuby::Repository::NoSuchShaFound
end

#default_committer_email ⇒ Object

Gets the default email for commits.

Returns the String email address.



605
606
607
608
 
# File 'lib/gollum/wiki.rb', line 605

def default_committer_email
  @default_committer_email ||= \
    @repo.config['user.email'] || self.class.default_committer_email
end

#default_committer_name ⇒ Object

Gets the default name for commits.

Returns the String name.



597
598
599
600
 
# File 'lib/gollum/wiki.rb', line 597

def default_committer_name
  @default_committer_name ||= \
    @repo.config['user.name'] || self.class.default_committer_name
end

#delete_page(page, commit) ⇒ Object

Public: Delete a page.

page - The Gollum::Page to delete. commit - The commit Hash details:

:message   - The String commit message.
:name      - The String author full name.
:email     - The String email address.
:parent    - Optional Grit::Commit parent to this update.
:tree      - Optional String SHA of the tree to create the
             index from.
:committer - Optional Gollum::Committer instance.  If provided,
             assume that this operation is part of batch of
             updates and the commit happens later.

Returns the String SHA1 of the newly written version, or the Gollum::Committer instance if this is part of a batch update.



326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
 
# File 'lib/gollum/wiki.rb', line 326

def delete_page(page, commit)
  multi_commit = false

  committer = if obj = commit[:committer]
    multi_commit = true
    obj
  else
    Committer.new(self, commit)
  end

  committer.delete(page.path)

  committer.after_commit do |index, sha|
    dir = ::File.dirname(page.path)
    dir = '' if dir == '.'

    @access.refresh
    index.update_working_dir(dir, page.filename_stripped, page.format)
  end

  multi_commit ? committer : committer.commit
end

#exist? ⇒ Boolean

Public: check whether the wiki’s git repo exists on the filesystem.

Returns true if the repo exists, and false if it does not.

Returns:

  • (Boolean) 


172
173
174
 
# File 'lib/gollum/wiki.rb', line 172

def exist?
  @access.exist?
end

#file(name, version = @ref) ⇒ Object

Public: Get the static file for a given name.

name - The full String pathname to the file. version - The String version ID to find (default: @ref).

Returns a Gollum::File or nil if no matching file was found.



192
193
194
 
# File 'lib/gollum/wiki.rb', line 192

def file(name, version = @ref)
  @file_class.new(self).find(name, version)
end

#full_reverse_diff(sha1, sha2 = nil) ⇒ Object

Creates a reverse diff for the given SHAs.

sha1 - String SHA1 of the earlier parent if two SHAs are given,

or the child.

sha2 - Optional String SHA1 of the child.

Returns a String of the reverse Diff to apply.



590
591
592
 
# File 'lib/gollum/wiki.rb', line 590

def full_reverse_diff(sha1, sha2 = nil)
  full_reverse_diff_for(nil, sha1, sha2)
end

#full_reverse_diff_for(page, sha1, sha2 = nil) ⇒ Object

Creates a reverse diff for the given SHAs on the given Gollum::Page.

page - The Gollum::Page to scope the patch to, or a String Path. sha1 - String SHA1 of the earlier parent if two SHAs are given,

or the child.

sha2 - Optional String SHA1 of the child.

Returns a String of the reverse Diff to apply.



574
575
576
577
578
579
580
581
 
# File 'lib/gollum/wiki.rb', line 574

def full_reverse_diff_for(page, sha1, sha2 = nil)
  sha1, sha2 = "#{sha1}^", sha1 if sha2.nil?
  args = [{:R => true}, sha1, sha2]
  if page
    args << '--' << (page.respond_to?(:path) ? page.path : page.to_s)
  end
  repo.git.native(:diff, *args)
end

#history_sanitizer ⇒ Object

Public: Creates a Sanitize instance using the Wiki’s history sanitization options.

Returns a Sanitize instance.



499
500
501
502
503
 
# File 'lib/gollum/wiki.rb', line 499

def history_sanitizer
  if options = history_sanitization
    @history_sanitizer ||= options.to_sanitize
  end
end

#inspect ⇒ Object 



632
633
634
 
# File 'lib/gollum/wiki.rb', line 632

def inspect
  %(#<#{self.class.name}:#{object_id} #{@repo.path}>)
end

#log(options = {}) ⇒ Object

Public: All of the versions that have touched the Page.

options - The options Hash:

:page     - The Integer page number (default: 1).
:per_page - The Integer max count of items to return.

Returns an Array of Grit::Commit.



473
474
475
 
# File 'lib/gollum/wiki.rb', line 473

def log(options = {})
  @repo.log(@ref, nil, log_pagination_options(options))
end

#normalize(data) ⇒ Object

Normalize the data.

data - The String data to be normalized.

Returns the normalized data String.



535
536
537
 
# File 'lib/gollum/wiki.rb', line 535

def normalize(data)
  data.gsub(/\r/, '')
end

#page(name, version = @ref) ⇒ Object

Public: Get the formatted page for a given page name.

name - The human or canonical String page name of the wiki page. version - The String version ID to find (default: @ref).

Returns a Gollum::Page or nil if no matching page was found.



182
183
184
 
# File 'lib/gollum/wiki.rb', line 182

def page(name, version = @ref)
  @page_class.new(self).find(name, version)
end

#page_file_name(name, format) ⇒ Object

Assemble a Page’s filename from its name and format.

name - The String name of the page (should be pre-canonicalized). format - The Symbol format of the page.

Returns the String filename.



545
546
547
 
# File 'lib/gollum/wiki.rb', line 545

def page_file_name(name, format)
  name + '.' + @page_class.format_to_ext(format)
end

#pages(treeish = nil) ⇒ Object

Public: Lists all pages for this wiki.

treeish - The String commit ID or ref to find (default: @ref)

Returns an Array of Gollum::Page instances.



429
430
431
 
# File 'lib/gollum/wiki.rb', line 429

def pages(treeish = nil)
  tree_list(treeish || @ref)
end

#preview_page(name, data, format) ⇒ Object

Public: Create an in-memory Page with the given data and format. This is useful for previewing what content will look like before committing it to the repository.

name - The String name of the page. format - The Symbol format of the page. data - The new String contents of the page.

Returns the in-memory Gollum::Page.



205
206
207
208
209
210
211
212
213
 
# File 'lib/gollum/wiki.rb', line 205

def preview_page(name, data, format)
  page = @page_class.new(self)
  ext  = @page_class.format_to_ext(format.to_sym)
  name = @page_class.cname(name) + '.' + ext
  blob = OpenStruct.new(:name => name, :data => data)
  page.populate(blob)
  page.version = @access.commit('master')
  page
end

#revert_commit(sha1, sha2 = nil, commit = {}) ⇒ Object

Public: Applies a reverse diff to the repo. If only 1 SHA is given, the reverse diff will be taken from its parent (^SHA…SHA). If two SHAs are given, the reverse diff is taken from SHA1…SHA2.

sha1 - String SHA1 of the earlier parent if two SHAs are given,

or the child.

sha2 - Optional String SHA1 of the child. commit - The commit Hash details:

:message - The String commit message.
:name    - The String author full name.
:email   - The String email address.

Returns a String SHA1 of the new commit, or nil if the reverse diff does not apply.



420
421
422
 
# File 'lib/gollum/wiki.rb', line 420

def revert_commit(sha1, sha2 = nil, commit = {})
  revert_page(nil, sha1, sha2, commit)
end

#revert_page(page, sha1, sha2 = nil, commit = {}) ⇒ Object

Public: Applies a reverse diff for a given page. If only 1 SHA is given, the reverse diff will be taken from its parent (^SHA…SHA). If two SHAs are given, the reverse diff is taken from SHA1…SHA2.

page - The Gollum::Page to delete. sha1 - String SHA1 of the earlier parent if two SHAs are given,

or the child.

sha2 - Optional String SHA1 of the child. commit - The commit Hash details:

:message - The String commit message.
:name    - The String author full name.
:email   - The String email address.
:parent  - Optional Grit::Commit parent to this update.

Returns a String SHA1 of the new commit, or nil if the reverse diff does not apply.



365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
 
# File 'lib/gollum/wiki.rb', line 365

def revert_page(page, sha1, sha2 = nil, commit = {})
  if sha2.is_a?(Hash)
    commit = sha2
    sha2   = nil
  end

  patch     = full_reverse_diff_for(page, sha1, sha2)
  committer = Committer.new(self, commit)
  parent    = committer.parents[0]
  committer.options[:tree] = @repo.git.apply_patch(parent.sha, patch)
  return false unless committer.options[:tree]
  committer.after_commit do |index, sha|
    @access.refresh

    files = []
    if page
      files << [page.path, page.filename_stripped, page.format]
    else
      # Grit::Diff can't parse reverse diffs.... yet
      patch.each_line do |line|
        if line =~ %r{^diff --git b/.+? a/(.+)$}
          path = $1
          ext  = ::File.extname(path)
          name = ::File.basename(path, ext)
          if format = ::Gollum::Page.format_for(ext)
            files << [path, name, format]
          end
        end
      end
    end

    files.each do |(path, name, format)|
      dir = ::File.dirname(path)
      dir = '' if dir == '.'
      index.update_working_dir(dir, name, format)
    end
  end

  committer.commit
end

#sanitizer ⇒ Object

Public: Creates a Sanitize instance using the Wiki’s sanitization options.

Returns a Sanitize instance.



489
490
491
492
493
 
# File 'lib/gollum/wiki.rb', line 489

def sanitizer
  if options = sanitization
    @sanitizer ||= options.to_sanitize
  end
end

#search(query) ⇒ Object

Public: Search all pages for this wiki.

query - The string to search for

Returns an Array with Objects of page name and count of matches



451
452
453
454
455
456
457
458
459
460
461
462
463
464
 
# File 'lib/gollum/wiki.rb', line 451

def search(query)
  args = [{}, '-i', '-c', query, @ref, '--']
  args << '--' << @page_file_dir if @page_file_dir

  @repo.git.grep(*args).split("\n").map! do |line|
    result = line.split(':')
    file_name = Gollum::Page.canonicalize_filename(::File.basename(result[1]))

    {
      :count  => result[2].to_i,
      :name   => file_name
    }
  end
end

#size(ref = nil) ⇒ Object

Public: Returns the number of pages accessible from a commit

ref - A String ref that is either a commit SHA or references one.

Returns a Fixnum



438
439
440
441
442
443
444
 
# File 'lib/gollum/wiki.rb', line 438

def size(ref = nil)
  tree_map_for(ref || @ref).inject(0) do |num, entry|
    num + (@page_class.valid_page_name?(entry.name) ? 1 : 0)
  end
rescue Grit::GitRuby::Repository::NoSuchShaFound
  0
end

#tree_list(ref) ⇒ Object

Fill an array with a list of pages.

ref - A String ref that is either a commit SHA or references one.

Returns a flat Array of Gollum::Page instances.



554
555
556
557
558
559
560
561
562
563
564
 
# File 'lib/gollum/wiki.rb', line 554

def tree_list(ref)
  if sha = @access.ref_to_sha(ref)
    commit = @access.commit(sha)
    tree_map_for(sha).inject([]) do |list, entry|
      next list unless @page_class.valid_page_name?(entry.name)
      list << entry.page(self, commit)
    end
  else
    []
  end
end

#tree_map_for(ref) ⇒ Object

Finds a full listing of files and their blob SHA for a given ref. Each listing is cached based on its actual commit SHA.

ref - A String ref that is either a commit SHA or references one.

Returns an Array of BlobEntry instances.



626
627
628
629
630
 
# File 'lib/gollum/wiki.rb', line 626

def tree_map_for(ref)
  @access.tree(ref)
rescue Grit::GitRuby::Repository::NoSuchShaFound
  []
end

#update_page(page, name, format, data, commit = {}) ⇒ Object

Public: Update an existing page with new content. The location of the page inside the repository will not change. If the given format is different than the current format of the page, the filename will be changed to reflect the new format.

page - The Gollum::Page to update. name - The String extension-less name of the page. format - The Symbol format of the page. data - The new String contents of the page. commit - The commit Hash details:

:message   - The String commit message.
:name      - The String author full name.
:email     - The String email address.
:parent    - Optional Grit::Commit parent to this update.
:tree      - Optional String SHA of the tree to create the
             index from.
:committer - Optional Gollum::Committer instance.  If provided,
             assume that this operation is part of batch of
             updates and the commit happens later.

Returns the String SHA1 of the newly written version, or the Gollum::Committer instance if this is part of a batch update.



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/gollum/wiki.rb', line 277

def update_page(page, name, format, data, commit = {})
  name   ||= page.name
  format ||= page.format
  dir      = ::File.dirname(page.path)
  dir      = '' if dir == '.'
  filename = (rename = page.name != name) ?
    Gollum::Page.cname(name) : page.filename_stripped

  multi_commit = false

  committer = if obj = commit[:committer]
    multi_commit = true
    obj
  else
    Committer.new(self, commit)
  end

  if !rename && page.format == format
    committer.add(page.path, normalize(data))
  else
    committer.delete(page.path)
    committer.add_to_index(dir, filename, format, data, :allow_same_ext)
  end

  committer.after_commit do |index, sha|
    @access.refresh
    index.update_working_dir(dir, page.filename_stripped, page.format)
    index.update_working_dir(dir, filename, format)
  end

  multi_commit ? committer : committer.commit
end

#write_page(name, format, data, commit = {}) ⇒ Object

Public: Write a new version of a page to the Gollum repo root.

name - The String name of the page. format - The Symbol format of the page. data - The new String contents of the page. commit - The commit Hash details:

:message   - The String commit message.
:name      - The String author full name.
:email     - The String email address.
:parent    - Optional Grit::Commit parent to this update.
:tree      - Optional String SHA of the tree to create the
             index from.
:committer - Optional Gollum::Committer instance.  If provided,
             assume that this operation is part of batch of
             updates and the commit happens later.

Returns the String SHA1 of the newly written version, or the Gollum::Committer instance if this is part of a batch update.



233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/gollum/wiki.rb', line 233

def write_page(name, format, data, commit = {})
  multi_commit = false

  committer = if obj = commit[:committer]
    multi_commit = true
    obj
  else
    Committer.new(self, commit)
  end

  filename = Gollum::Page.cname(name)

  committer.add_to_index('', filename, format, data)

  committer.after_commit do |index, sha|
    @access.refresh
    index.update_working_dir('', filename, format)
  end

  multi_commit ? committer : committer.commit
end