pickaxe - the redmine wiki editor

pickaxe https://example.com/projects/example/

Pickaxe is a ncurses based programm to view and edit redmine wiki pages.

When you start pickaxe your are prompted for your username and passwort if those are not set in the configuration file. The index is the first screen you see. It is a list of alle wiki pages in your current project. You can use Return to view a wiki page in the pager screen.

To edit a page, press the e key while in the index or pager screen. This will open the page in an editor, where you can make changes to the page text.

You can also search for pages by pressing the s key while in the index screen. This will prompt you for a search term. Type in the term you want to search for, and pickaxe will display a list of all pages that match the search term.

In pickaxe, you can press the c key while in the index screen to enter the project switcher. This will display a list of all the projects you have access to. You can use the arrow keys to navigate the list, press Enter to select a project, or press q to cancel and return to the index screen.

After selecting a project, the index screen will display the list of wiki pages for that project. From there, you can use the same navigation and editing commands as described earlier.

To exit pickaxe, press the q key while in the index screen. This will bring you back to the command prompt.

When pickaxe is first invoked, it will attempt to read its configuration file at $XDG_CONFIG_HOME/pickaxe/pickaxe.conf

An configuration file consists of a series of commands. The only valid commands are set and bind. The set command is used to change configuration variables, while bind allows the user to change the default key bindings.

The bind command is used to change the default key bindings. The syntax for the bind command is as follows:

bind map key function

map

This is the name of the keymap that the user wishes to modify. pickaxe has these keymaps: pager, index, links, attachments and projects.

key

This is the key or key combination that the user wants to bind to the specified function.

function

This is the name of the function that the user wants to bind to the specified key or key combination. Press ? to see a list of valid functions for the current map.

For example, to bind the next_line function to the j key in the index keymap, the following command can be used:

bind index j next_line

With this binding, whenever the j key is pressed while in the index, the next_line function will be executed.

The set command is used to changed configuration variables. It takes the variable name and its new value as arguments. For example:

set pass_cmd pass [email protected]

The following variables are valid:

pass_cmd

Command to get the users password. It should return the password on stdout on a sinlge line. There is no default.

yank_cmd

Command to copy the url of the current wiki page to the clipboard. Defaults to xclip.

username

Specifies the username for you redmine account. If this and REDMINE_APIKEY are no set pickaxe will prompt you for your username. There is no default.

password

Specifies the passwort for you redmine account. If this and REDMINE_APIKEY are no set pickaxe will prompt you for your password. There is no default.

base_url

Specifies the base url of the redmine project you want to work on.

pager_index_lines

Determines the number of lines of a mini-index which is shown when in the pager. The default value of 0 results in no index being shown.

index_format

This variable allows you to customize the index display. It uses format strings similar to the C function printf(3) to format output. The default is '%4n %-22{%Y-%m-%d %H:%M:%S}u %t'.

The following sequences are defined:

%n

Current page number.

%{strftime_format}u

The page's last update date formatted using strftime_format.

%{strftime_format}c

The page's creation date formatted using strftime_format.

%t

The page title. If threading is activated the tree characters are added.

%v

The page version number.

REDMINE_APIKEY

This variable has to be set in order to access the redmine api. You can access it by clicking on your account on your redmine wiki and search for api key in the right margin.

If you have cpanminus installed, you can install pickaxe by simply calling:

$ cpanm .

Or you can use:

$ perl Makefile.PL && make install

But you don't have to install pickaxe to use it. You can just fullfull its dependencies (this example assumes you're running Debian but the packages have similar names in other distributions) and then run it from inside your checkout:

$ apt-get install libmojolicious-perl libcurses-perl libio-socket-ssl-perl
$ perl -Ilib bin/pickaxe

Or you can use docker to run pickaxe:

$ docker build -t pickaxe .
$ docker run --net=host --rm -ti pickaxe

Packaging instructions for NixOS and Debian are included in the source tree.

Copyright 2022 Mario Domgoergen <[email protected]>

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http:https://www.gnu.org/licenses/>.