Class: Gollum::Wiki

Inherits:
Object
  • Object
show all
Includes:
Pagination
Defined in:
lib/gollum-lib/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:

:universal_toc - Table of contents on all pages.  Default: false
:live_preview  - Livepreview editing for markdown files. Default: true
: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.
:mathjax       - Set to false to disable mathjax.
:user_icons    - Enable user icons on the history page. [gravatar, identicon, none].
                 Default: none
:show_all      - Show all files in file view, not just valid pages.
                 Default: false
:collapse_tree - Start with collapsed file view. Default: false
:css           - Include the custom.css file from the repo.
:emoji         - Parse and interpret emoji tags (e.g. :heart:).
:h1_title      - Concatenate all h1's on a page to form the
                 page title.
:index_page    - The default page to retrieve or create if the
                 a directory is accessed.
:bar_side      - Where the sidebar should be displayed, may be:
                  - :left
                  - :right
:allow_uploads - Set to true to allow file uploads.
:per_page_uploads - Whether uploads should be stored in a central
                 'uploads' directory, or in a directory named for
                 the page they were uploaded to.
:filter_chain  - Override the default filter chain with your own.

Returns a fresh Gollum::Repo.



212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/gollum-lib/wiki.rb', line 212

def initialize(path, options = {})
  options = self.class.default_options.merge(options)
  if path.is_a?(GitAccess)
    options[:access] = path
    path             = path.path
  end

  # Use .fetch instead of ||
  #
  # o = { :a => false }
  # o[:a] || true # => true
  # o.fetch :a, true # => false

  @path                 = path
  @repo_is_bare         = options.fetch :repo_is_bare, nil
  @page_file_dir        = options.fetch :page_file_dir, nil
  @access               = options.fetch :access, GitAccess.new(path, @page_file_dir, @repo_is_bare)
  @base_path            = options.fetch :base_path, "/"
  @page_class           = options.fetch :page_class, self.class.page_class
  @file_class           = options.fetch :file_class, self.class.file_class
  @markup_classes       = options.fetch :markup_classes, self.class.markup_classes
  @repo                 = @access.repo
  @ref                  = options.fetch :ref, self.class.default_ref
  @sanitization         = options.fetch :sanitization, self.class.sanitization
  @ws_subs              = options.fetch :ws_subs, self.class.default_ws_subs
  @history_sanitization = options.fetch :history_sanitization, self.class.history_sanitization
  @live_preview         = options.fetch :live_preview, true
  @universal_toc        = options.fetch :universal_toc, false
  @mathjax              = options.fetch :mathjax, false
  @show_all             = options.fetch :show_all, false
  @collapse_tree        = options.fetch :collapse_tree, false
  @css                  = options.fetch :css, false
  @emoji                = options.fetch :emoji, false
  @h1_title             = options.fetch :h1_title, false
  @index_page           = options.fetch :index_page, 'Home'
  @bar_side             = options.fetch :sidebar, :right
  @user_icons           = ['gravatar', 'identicon'].include?(options[:user_icons]) ?
      options[:user_icons] : 'none'
  @allow_uploads        = options.fetch :allow_uploads, false
  @per_page_uploads     = options.fetch :per_page_uploads, false
  @filter_chain         = options.fetch :filter_chain,
                                        [:Metadata, :PlainText, :TOC, :RemoteCode, :Code, :Macro, :Emoji, :Sanitize, :WSD, :PlantUML, :Tags, :Render]
  @filter_chain.delete(:Emoji) unless options.fetch :emoji, false
end

Class Attribute Details

.default_committer_email ⇒ Object 



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

def default_committer_email
  @default_committer_email || '[email protected]'
end

.default_committer_name ⇒ Object 



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

def default_committer_name
  @default_committer_name || 'Anonymous'
end

.default_options ⇒ Object 



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

def default_options
  @default_options || {}
end

.default_ref ⇒ Object 



109
110
111
 
# File 'lib/gollum-lib/wiki.rb', line 109

def default_ref
  @default_ref || 'master'
end

.default_ws_subs ⇒ Object 



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

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.



53
54
55
56
57
58
59
60
 
# File 'lib/gollum-lib/wiki.rb', line 53

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.



100
101
102
103
104
105
106
107
 
# File 'lib/gollum-lib/wiki.rb', line 100

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



64
65
66
67
68
69
70
71
 
# File 'lib/gollum-lib/wiki.rb', line 64

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.



42
43
44
45
46
47
48
49
 
# File 'lib/gollum-lib/wiki.rb', line 42

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.



91
92
93
94
95
96
 
# File 'lib/gollum-lib/wiki.rb', line 91

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

Instance Attribute Details

#allow_uploads ⇒ Object (readonly)

Toggles file upload functionality.



846
847
848
 
# File 'lib/gollum-lib/wiki.rb', line 846

def allow_uploads
  @allow_uploads
end

#bar_side ⇒ Object (readonly)

Gets side on which the sidebar should be shown



165
166
167
 
# File 'lib/gollum-lib/wiki.rb', line 165

def bar_side
  @bar_side
end

#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 “/”.



133
134
135
 
# File 'lib/gollum-lib/wiki.rb', line 133

def base_path
  @base_path
end

#collapse_tree ⇒ Object (readonly)

Start with collapsed file view. Default: false



843
844
845
 
# File 'lib/gollum-lib/wiki.rb', line 843

def collapse_tree
  @collapse_tree
end

#css ⇒ Object (readonly)

Injects custom css from custom.css in root repo. Defaults to false



155
156
157
 
# File 'lib/gollum-lib/wiki.rb', line 155

def css
  @css
end

#file_class ⇒ Object (readonly)

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



824
825
826
 
# File 'lib/gollum-lib/wiki.rb', line 824

def file_class
  @file_class
end

#filter_chain ⇒ Object (readonly)

An array of symbols which refer to classes under Gollum::Filter, each of which is an element in the “filtering chain”. See the documentation for Gollum::Filter for more on how this chain works, and what filter classes need to implement.



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

def filter_chain
  @filter_chain
end

#h1_title ⇒ Object (readonly)

Sets page title to value of first h1 Defaults to false



159
160
161
 
# File 'lib/gollum-lib/wiki.rb', line 159

def h1_title
  @h1_title
end

#history_sanitization ⇒ Object (readonly)

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



139
140
141
 
# File 'lib/gollum-lib/wiki.rb', line 139

def history_sanitization
  @history_sanitization
end

#index_page ⇒ Object (readonly)

Gets the custom index page for / and subdirs (e.g. foo/)



162
163
164
 
# File 'lib/gollum-lib/wiki.rb', line 162

def index_page
  @index_page
end

#live_preview ⇒ Object (readonly)

Gets the boolean live preview value.



151
152
153
 
# File 'lib/gollum-lib/wiki.rb', line 151

def live_preview
  @live_preview
end

#markup_classes ⇒ Object (readonly)

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



827
828
829
 
# File 'lib/gollum-lib/wiki.rb', line 827

def markup_classes
  @markup_classes
end

#mathjax ⇒ Object (readonly)

Toggles mathjax.



833
834
835
 
# File 'lib/gollum-lib/wiki.rb', line 833

def mathjax
  @mathjax
end

#page_class ⇒ Object (readonly)

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



821
822
823
 
# File 'lib/gollum-lib/wiki.rb', line 821

def page_class
  @page_class
end

#page_file_dir ⇒ Object (readonly)

Gets the String directory in which all page files reside.



145
146
147
 
# File 'lib/gollum-lib/wiki.rb', line 145

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.



818
819
820
 
# File 'lib/gollum-lib/wiki.rb', line 818

def path
  @path
end

#per_page_uploads ⇒ Object (readonly)

Toggles whether uploaded files go into ‘uploads’, or a directory named after the page they were uploaded to.



850
851
852
 
# File 'lib/gollum-lib/wiki.rb', line 850

def per_page_uploads
  @per_page_uploads
end

#ref ⇒ Object (readonly)

Gets the String ref in which all page files reside.



142
143
144
 
# File 'lib/gollum-lib/wiki.rb', line 142

def ref
  @ref
end

#repo ⇒ Object (readonly)

The Gollum::Git::Repo associated with the wiki.

Returns the Gollum::Git::Repo.



813
814
815
 
# File 'lib/gollum-lib/wiki.rb', line 813

def repo
  @repo
end

#sanitization ⇒ Object (readonly)

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



136
137
138
 
# File 'lib/gollum-lib/wiki.rb', line 136

def sanitization
  @sanitization
end

#show_all ⇒ Object (readonly)

Toggles showing all files in files view. Default is false. When false, only valid pages in the git repo are displayed.



840
841
842
 
# File 'lib/gollum-lib/wiki.rb', line 840

def show_all
  @show_all
end

#universal_toc ⇒ Object (readonly)

Toggles display of universal table of contents



830
831
832
 
# File 'lib/gollum-lib/wiki.rb', line 830

def universal_toc
  @universal_toc
end

#user_icons ⇒ Object (readonly)

Toggles user icons. Default: ‘none’



836
837
838
 
# File 'lib/gollum-lib/wiki.rb', line 836

def user_icons
  @user_icons
end

#ws_subs ⇒ Object (readonly)

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



148
149
150
 
# File 'lib/gollum-lib/wiki.rb', line 148

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



75
76
77
 
# File 'lib/gollum-lib/wiki.rb', line 75

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



81
82
83
84
 
# File 'lib/gollum-lib/wiki.rb', line 81

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

Instance Method Details

#add_filter(name, loc) ⇒ Object

Public: Add an additional link to the filter chain.

name - A symbol which represents the name of a class under the

Gollum::Render namespace to insert into the chain.

loc - A “location specifier” – that is, where to put the new

filter in the chain.  This can be one of `:first`, `:last`,
`:before => :SomeElement`, or `:after => :SomeElement`, where
`:SomeElement` (if specified) is a symbol already in the
filter chain.  A `:before` or `:after` which references a
filter that doesn't exist will cause `ArgumentError` to be
raised.

Returns nothing.



750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
 
# File 'lib/gollum-lib/wiki.rb', line 750

def add_filter(name, loc)
  unless name.is_a? Symbol
    raise ArgumentError,
          "Invalid filter name #{name.inspect} (must be a symbol)"
  end

  case loc
    when :first
      @filter_chain.unshift(name)
    when :last
      @filter_chain.push(name)
    when Hash
      if loc.length != 1
        raise ArgumentError,
              "Invalid location specifier"
      end
      if ([:before, :after] && loc.keys).empty?
        raise ArgumentError,
              "Invalid location specifier"
      end

      next_to  = loc.values.first
      relative = loc.keys.first

      i = @filter_chain.index(next_to)
      if i.nil?
        raise ArgumentError,
              "Unknown filter #{next_to.inspect}"
      end

      i += 1 if relative == :after
      @filter_chain.insert(i, name)
    else
      raise ArgumentError,
            "Invalid location specifier"
  end
end

#clear_cache ⇒ Object

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

Returns nothing.



712
713
714
 
# File 'lib/gollum-lib/wiki.rb', line 712

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 Gollum::Git::Commit instance.



960
961
962
963
 
# File 'lib/gollum-lib/wiki.rb', line 960

def commit_for(ref)
  @access.commit(ref)
rescue Gollum::Git::NoSuchShaFound
end

#default_committer_email ⇒ Object

Gets the default email for commits.

Returns the String email address.



949
950
951
952
953
 
# File 'lib/gollum-lib/wiki.rb', line 949

def default_committer_email
  email = @repo.config['user.email']
  email = email.delete('<>') if email
  @default_committer_email ||= email || self.class.default_committer_email
end

#default_committer_name ⇒ Object

Gets the default name for commits.

Returns the String name.



941
942
943
944
 
# File 'lib/gollum-lib/wiki.rb', line 941

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

#delete_file(path, commit) ⇒ Object

Public: Delete a file.

path - The path to the file 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 Gollum::Git::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.



518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
 
# File 'lib/gollum-lib/wiki.rb', line 518

def delete_file(path, commit)
  dir      = ::File.dirname(path)
  ext      = ::File.extname(path)
  format   = ext.split('.').last || 'txt'
  filename = ::File.basename(path, ext)

  multi_commit = !!commit[:committer]
  committer    = multi_commit ? commit[:committer] : Committer.new(self, commit)

  committer.delete(path)

  committer.after_commit do |index, _sha|
    dir = '' if dir == '.'

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

  multi_commit ? committer : committer.commit
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 Gollum::Git::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.



484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
 
# File 'lib/gollum-lib/wiki.rb', line 484

def delete_page(page, commit)

  multi_commit = !!commit[:committer]
  committer    = multi_commit ? commit[:committer] : Committer.new(self, commit)

  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) 


260
261
262
 
# File 'lib/gollum-lib/wiki.rb', line 260

def exist?
  @access.exist?
end

#file(name, version = @ref, try_on_disk = false) ⇒ 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). try_on_disk - If true, try to return just a reference to a file

that exists on the disk.

Returns a Gollum::File or nil if no matching file was found. Note that if you specify try_on_disk=true, you may or may not get a file for which on_disk? is actually true.



297
298
299
 
# File 'lib/gollum-lib/wiki.rb', line 297

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

#file_list(ref) ⇒ Object

Fill an array with a list of files.

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

Returns a flat Array of Gollum::File instances.



897
898
899
900
901
902
903
904
905
906
907
908
 
# File 'lib/gollum-lib/wiki.rb', line 897

def file_list(ref)
  if (sha = @access.ref_to_sha(ref))
    commit = @access.commit(sha)
    tree_map_for(sha).inject([]) do |list, entry|
      next list if entry.name.start_with?('_')
      next list if @page_class.valid_page_name?(entry.name)
      list << entry.file(self, commit)
    end
  else
    []
  end
end

#files(treeish = nil) ⇒ Object

Public: Lists all non-page files for this wiki.

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

Returns an Array of Gollum::File instances.



637
638
639
 
# File 'lib/gollum-lib/wiki.rb', line 637

def files(treeish = nil)
  file_list(treeish || @ref)
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.



934
935
936
 
# File 'lib/gollum-lib/wiki.rb', line 934

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.



918
919
920
921
922
923
924
925
 
# File 'lib/gollum-lib/wiki.rb', line 918

def full_reverse_diff_for(page, sha1, sha2 = nil)
  sha1, sha2 = "#{sha1}^", sha1 if sha2.nil?
  if page
    path = (page.respond_to?(:path) ? page.path : page.to_s)
    return repo.diff(sha2, sha1, path).first.diff
  end
  repo.diff(sha2, sha1).map { |d| d.diff }.join("\n")
end

#history_sanitizer ⇒ Object

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

Returns a Sanitize instance.



730
731
732
733
734
 
# File 'lib/gollum-lib/wiki.rb', line 730

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

#inspect ⇒ Object 



983
984
985
 
# File 'lib/gollum-lib/wiki.rb', line 983

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

#latest_changes(options = {}) ⇒ Object

Returns the latest changes in the wiki (globally)

options - The options Hash:

:max_count  - The Integer number of items to return.

Returns an Array of Gollum::Git::Commit.



703
704
705
706
 
# File 'lib/gollum-lib/wiki.rb', line 703

def latest_changes(options={})
  options[:max_count] = 10 unless options[:max_count]
  @repo.log(@ref, nil, options)
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 Gollum::Git::Commit.



693
694
695
 
# File 'lib/gollum-lib/wiki.rb', line 693

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.



857
858
859
 
# File 'lib/gollum-lib/wiki.rb', line 857

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

#page(name, version = @ref, dir = nil, exact = false) ⇒ Object

Public: Get the formatted page for a given page name, version, and dir.

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

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



271
272
273
274
 
# File 'lib/gollum-lib/wiki.rb', line 271

def page(name, version = @ref, dir = nil, exact = false)
  version = @ref if version.nil?
  @page_class.new(self).find(name, version, dir, exact)
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.



867
868
869
 
# File 'lib/gollum-lib/wiki.rb', line 867

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

#paged(name, dir = nil, exact = false, version = @ref) ⇒ Object

Public: Convenience method instead of calling page(name, nil, dir).

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

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



283
284
285
 
# File 'lib/gollum-lib/wiki.rb', line 283

def paged(name, dir = nil, exact = false, version = @ref)
  page(name, version, dir, exact)
end

#pages(treeish = nil, limit: nil, sort: nil, direction_desc: false) ⇒ 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.



619
620
621
622
623
624
625
626
627
628
629
630
 
# File 'lib/gollum-lib/wiki.rb', line 619

def pages(treeish = nil, limit: nil, sort: nil, direction_desc: false)
  sha = @access.ref_to_sha(treeish || ref)
  return [] unless sha
  commit = @access.commit(sha)

  blobs = tree_map_for(sha).select do |entry|
    @page_class.valid_page_name?(entry.name)
  end

  sorter = Gollum::Sorters::WikiSorter.new(sort, direction_desc, limit)
  sorter.call(sha, @access, blobs).map { |blob| blob.page(self, commit) }
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.



310
311
312
313
314
315
316
317
318
 
# File 'lib/gollum-lib/wiki.rb', line 310

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, :is_symlink => false)
  page.populate(blob)
  page.version = @access.commit(@ref)
  page
end

#remove_filter(name) ⇒ Object

Remove the named filter from the filter chain.

Returns nothing. Raises ‘ArgumentError` if the named filter doesn’t exist in the chain.



792
793
794
795
796
797
798
799
800
801
802
 
# File 'lib/gollum-lib/wiki.rb', line 792

def remove_filter(name)
  unless name.is_a? Symbol
    raise ArgumentError,
          "Invalid filter name #{name.inspect} (must be a symbol)"
  end

  unless @filter_chain.delete(name)
    raise ArgumentError,
          "#{name.inspect} not found in filter chain"
  end
end

#rename_page(page, rename, commit = {}) ⇒ Object

Public: Rename an existing page without altering content.

page - The Gollum::Page to update. rename - The String extension-less full path of the page (leading ‘/’ is ignored). commit - The commit Hash details:

:message   - The String commit message.
:name      - The String author full name.
:email     - The String email address.
:parent    - Optional Gollum::Git::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. Returns false if the operation is a NOOP.



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
405
406
407
408
409
410
411
412
413
414
415
416
417
418
 
# File 'lib/gollum-lib/wiki.rb', line 378

def rename_page(page, rename, commit = {})
  return false if page.nil?
  return false if rename.nil? || rename.empty?

  (target_dir, target_name) = ::File.split(rename.gsub(' ', '-'))
  (source_dir, source_name) = ::File.split(page.path)
  source_name               = page.filename_stripped

  # File.split gives us relative paths with ".", commiter.add_to_index doesn't like that.
  target_dir                = '' if target_dir == '.'
  source_dir                = '' if source_dir == '.'
  target_dir                = target_dir.gsub(/^\//, '') # rubocop:disable Style/RegexpLiteral

  # if the rename is a NOOP, abort
  if source_dir == target_dir && source_name == target_name
    return false
  end

  multi_commit = !!commit[:committer]
  committer    = multi_commit ? commit[:committer] : Committer.new(self, commit)

  # This piece only works for multi_commit
  # If we are in a commit batch and one of the previous operations
  # has updated the page, any information we ask to the page can be outdated.
  # Therefore, we should ask first to the current committer tree to see if
  # there is any updated change.
  raw_data = raw_data_in_committer(committer, source_dir, page.filename) ||
    raw_data_in_committer(committer, source_dir, "#{target_name}.#{Page.format_to_ext(page.format)}") ||
    page.raw_data

  committer.delete(page.path)
  committer.add_to_index(target_dir, target_name, page.format, raw_data)

  committer.after_commit do |index, _sha|
    @access.refresh
    index.update_working_dir(source_dir, source_name, page.format)
    index.update_working_dir(target_dir, target_name, page.format)
  end

  multi_commit ? committer : committer.commit
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.



610
611
612
 
# File 'lib/gollum-lib/wiki.rb', line 610

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 Gollum::Git::Commit parent to this update.

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



555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
 
# File 'lib/gollum-lib/wiki.rb', line 555

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 = Regexp.last_match[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.



720
721
722
723
724
 
# File 'lib/gollum-lib/wiki.rb', line 720

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



659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
 
# File 'lib/gollum-lib/wiki.rb', line 659

def search(query)
  options = {:path => page_file_dir, :ref => ref}
  results = {}
  @repo.git.grep(query, options).each do |hit|
    name = hit[:name]
    count = hit[:count]
    # Remove ext only from known extensions.
    # test.pdf => test.pdf, test.md => test
    file_name = Page::valid_page_name?(name) ? name.chomp(::File.extname(name)) : name
    results[file_name] = count.to_i
  end

  # Use git ls-files '*query*' to search for file names. Grep only searches file content.
  # Spaces are converted to dashes when saving pages to disk.
  @repo.git.ls_files(query.gsub(' ','-'), options).each do |path|
    # Remove ext only from known extensions.
    file_name          = Page::valid_page_name?(path) ? path.chomp(::File.extname(path)) : path
    # If there's not already a result for file_name then
    # the value is nil and nil.to_i is 0.
    results[file_name] = results[file_name].to_i + 1;
  end

  results.map do |key, val|
    { :count => val, :name => key }
  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



646
647
648
649
650
651
652
 
# File 'lib/gollum-lib/wiki.rb', line 646

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 Gollum::Git::NoSuchShaFound
  0
end

#tree_list(ref, limit: nil) ⇒ 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.



876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
 
# File 'lib/gollum-lib/wiki.rb', line 876

def tree_list(ref, limit: nil)
  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)
      break list if limit && list.size >= limit

      list
    end
  else
    []
  end
end

#tree_map_for(ref, ignore_page_file_dir = false) ⇒ 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. ignore_page_file_dir - Boolean, if true, searches all files within the git repo, regardless of dir/subdir

Returns an Array of BlobEntry instances.



972
973
974
975
976
977
978
979
980
981
 
# File 'lib/gollum-lib/wiki.rb', line 972

def tree_map_for(ref, ignore_page_file_dir=false)
  if ignore_page_file_dir && !@page_file_dir.nil?
    @root_access ||= GitAccess.new(path, nil, @repo_is_bare)
    @root_access.tree(ref)
  else
    @access.tree(ref)
  end
rescue Gollum::Git::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 Gollum::Git::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.



442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
 
# File 'lib/gollum-lib/wiki.rb', line 442

def update_page(page, name, format, data, commit = {})
  name = name ? ::File.basename(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 = !!commit[:committer]
  committer    = multi_commit ? commit[:committer] : Committer.new(self, commit)

  if !rename && page.format == format
    committer.add(page.path, normalize(data))
  else
    committer.delete(page.path)
    committer.add_to_index(dir, filename, format, data)
  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 = {}, dir = '') ⇒ 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 Gollum::Git::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.

dir - The String subdirectory of the Gollum::Page without any

prefix or suffix slashes (e.g. "foo/bar").

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



339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
 
# File 'lib/gollum-lib/wiki.rb', line 339

def write_page(name, format, data, commit = {}, dir = '')
  # spaces must be dashes
  sanitized_name = name.gsub(' ', '-')
  sanitized_dir  = dir.gsub(' ', '-')
  sanitized_dir  = ::File.join([@page_file_dir, sanitized_dir].compact)

  multi_commit = !!commit[:committer]
  committer    = multi_commit ? commit[:committer] : Committer.new(self, commit)

  filename = Gollum::Page.cname(sanitized_name)

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

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

  multi_commit ? committer : committer.commit
end