Rummage is designed to be easy to pick up. Its interface consists of three tabs: Search, Files, and Content. In the Search tab, a user specifies where they want to search, what they want to search for, and optionally what they want to replace it with. Search features can be tweaked with various options. The files that get searched can also be narrowed with patterns and filters.
Rummage uses the default regular expression library (Re) that comes with Python. It also optionally works with the 3rd party Regex library (if installed).
As matches are found, general info about the matches will be displayed in the Files and Content tabs. You can double click files to open them in your favorite editor (see Editor Preferences to configure Rummage for your editor).
Rummage also comes with a simple regular expression tester to test out patterns. It also provides a feature where patterns can be saved for later and/or frequent use. You can even create chains that will apply a series of saved searches.
Once Rummage is installed, you can run it from the command line (assuming your Python scripts/bin folder is in your system path):
rummage
If you have multiple Python versions installed, you can call Rummage for that specific Python version by appending the major and minor Python version to the end:
rummage3.6
In some environments, it may make sense to run Rummage with pythonw
which is mainly for launching GUI scripts (pythonw
is not available on Linux). In some environments, it may be required (see Running in Anaconda).
pythonw -m rummage
Search and replaces are configured in the Search tab which is broken up into 2 panels, the first of which is the Search & Replace panel. The second is the Limit Search panel.
The Search & Replace panel contains three text boxes with a dropdown history. The first text box defines where to search, the second defines what to search for, and the last defines what to replace matches with. You can select previously used patterns and search targets by expanding the dropdown panel for the input.
Below the text boxes are checkboxes that control the regular expression engine's options and features.
The available features will vary depending on which regular expression engine you are using. Each feature is documented in Search Options.
Lastly, Rummage provides buttons to launch a regular expression tester, dialogs to save or load frequently used regular expressions, and a dialog to create and manage regular expression chains.
The Limit Search panel contains checkboxes and inputs that filter the files to be searched. You can filter out hidden files, symlinks, files of specific sizes, or creation/modification dates.
You can also restrict which files get searched by providing a wild card (or regular expression if preferred) pattern. By default, the patterns are applied to the base file or folder name. See File Patterns to learn more about accepted wild card pattern syntax and how to configure optional file pattern features.
New 4.4.0
Added the symlink following via the Follow symlinks toggle.
Once a search or replace is initiated, the results will begin to appear in the Files and Content tabs. You can then double click a file to open it in your editor, or right click them to bring up a context menu with additional options.
Tip
You can hide/show columns by right clicking the list header to get a special context menu. You can then deselect or select the the column(s) you wish to hide/show respectively.
Rummage comes with a simple regular expression tester. It has a simple text box to place content to search, and another text box that will show the final results after the find and replace are applied. Below those text boxes, there are two text input boxes for the find pattern and the replace pattern. Lastly, all search and replace flag options are found under the patterns.
To use the tester, simply enter the content to search, set your desired options, and input your find and replace pattern. As you change your pattern or options, matches will be updated and highlighted, and the result box will be updated with any replacements.
When you are satisfied with your result, click the Use
button, and your pattern and settings will be populated in the main window.
Regular expressions can be very complex, and sometimes you might want to save them for future use.
When you have a pattern configured that you want to save, simply click the Save Search
button, and a dialog will pop up asking you to name the search. When done, click the Save
button on the dialog and your search patterns and options will be saved.
You'll notice that there are two input boxes. The first requires a unique name (only word characters, underscores, and hyphens are allowed). The second is an optional comment in case you wish to elaborate on what the pattern is for.
Underneath the inputs will be the actual search settings being saved.
To load a pattern that was saved previously, click the Load Search
button. You will be presented with a dialog showing all your saved searches. Highlight the pattern you want to load and click the Load
button. Your pattern and options will be populated in the main dialog.
If you wish to edit the name or comment of a search, you can double click the entry or click the "Edit" button.
There are times you may have a task that requires you to do multiple find and replaces that are all related, but are too difficult to represent as a single find and replace. This is where search chains can be helpful.
Search chains are essentially a sequence of multiple saved search and replace patterns. You can create a search chain by clicking the Search Chains
button which will bring up the search change manager.
Here you can create or delete search chains.
To use search chains, you must put Rummage in "search chain" mode by selecting the check box named Use search chains
in the main window. When "search chain" mode is enabled, all controls that don't apply to search chains will be disabled, and the search box will be replaced with a drop down for selecting existing chains you've already created. When a search is performed, Rummage will iterate over each file with all the saved searches in the chain.
Regular expressions are great, but sometimes regular expressions aren't enough. If you are dealing with a replace task that requires logic that cannot be represented in a simple replace pattern, you can create a "replace plugin".
Replace plugins are written in Python and are loaded by first selecting the Use plugin replace
check box in the main dialog.
Then the main dialog's Replace with
text box will become the Replace plugin
text box with an associated file picker. Here you can point to your replace plugin file.
Replace plugins aren't meant to be full, complex modules that import lots of other relative files. They are meant to be a single, compact script, but inside that script, you can import anything that is already installed in your Python environment.
Replace plugins should contain two things. The first is a plugin class derived from the rummage.lib.rumcore.ReplacePlugin
. The second is a function called get_replace
that returns your class.
The plugin class is fairly straight forward and is shown below.
class ReplacePlugin(object):
"""Rummage replace plugin."""
def __init__(self, file_info, flags):
"""Initialize."""
self.file_info = file_info
self.flags = flags
self.on_init()
def on_init(self):
"""Override this function to add initialization setup."""
def get_flags(self):
"""Get flags."""
return self.flags
def get_file_name(self):
"""Get file name."""
return self.file_info.name
def is_binary(self):
"""Is a binary search."""
return self.file_info.encoding.encode == 'bin'
def is_literal(self):
"""Is a literal search."""
return self.flags & LITERAL
def replace(self, m):
"""Make replacement."""
return m.group(0)
ReplacePlugin
's replace
function will receive the parameter m
which is either a regex
or re
match object (depending on what regular expression engine is selected). The return value must be either a Unicode string or byte string (for binary files).
The ReplacePlugin
's file_info
property is a named tuple providing information about the current file such as name, size, creation date, etc.
class FileInfoRecord(namedtuple('FileInfoRecord', ['id', 'name', 'size', 'modified', 'created', 'encoding'])):
"""A record for tracking file info."""
The ReplacePlugin
's flags
property contains only Rummage search related flags (the flags are abstracted at this level and are converted to the appropriate regular expression flags later). They can also be accessed from rummage.lib.rumcore
. The flags are shown below.
# Common regular expression flags (re|regex)
IGNORECASE = 0x1 # (?i)
DOTALL = 0x2 # (?s)
MULTILINE = 0x4 # (?m)
UNICODE = 0x8 # (?u)
# Regex module flags
ASCII = 0x10 # (?a)
FULLCASE = 0x20 # (?f)
WORD = 0x40 # (?w)
BESTMATCH = 0x80 # (?b)
ENHANCEMATCH = 0x100 # (?e)
REVERSE = 0x200 # (?r)
VERSION0 = 0x400 # (?V0)
VERSION1 = 0x800 # (?V1)
FORMATREPLACE = 0x1000 # Use {1} for groups in replace
POSIX = 0x2000 # (?p)
# Rumcore search related flags
LITERAL = 0x10000 # Literal search
Example Plugin
In the example below, we have a replace plugin that replaces the search result with the name of the file. It is assumed this is not a binary replace, so a Unicode string is returned.
from __future__ import unicode_literals
from rummage.lib import rumcore
import os
class TestReplace(rumcore.ReplacePlugin):
"""Replace object."""
def replace(self, m):
"""Replace method."""
name = os.path.basename(self.get_file_name())
return name
def get_replace():
"""Get the replace object."""
return TestReplace
Rummage allows the exporting of the results to either CSV or HTML. Simply select File→Export and pick either CSV or HTML. The HTML output will be styled similar to the GUI interface with the results in tables with sortable columns.
Large Result Sets
Really, really large sets of results will probably be best suited for CSV as a browser may have a hard time loading the entire data set at once.