Table of Contents
Dwcommits creates searchable databases of git/gitHub repositories with facilities for updating both the gits and the databases and displaying the results of queries made against the databases. It consists of both an adminstation plugin and a syntax plugin. Queries can be made in the administartion module but can be given more permanent form in the wiki pages through the use of the syntax plugin. The syntax plugin can be configured so that it automatically updates whenever the database is updated in the adminstration panel.
There are three components to the project, the git repository, and the sqlite database constructed from the repository, and a syntax plugin.
- Git Repository
- dwcommits gives you a range of choices for updating and querying git repositories on the local machine. It enables you to select between repositories and their branches, to check the git status, to pull in new commits from remote repository, to add and commit local files to the local repository, though not to push to the remote.
- Sqlite Database
- dwcommits creates its databases from the output of the git logs. You can choose to create the database from any point in the git history by setting the start date for the database in the admin panel. Dwcommits will create a new database for each repository. You can re-initialize a database and begin entering data from a new date.
- The databases can be queried from within the admin panel, where the output will be displayed. There is now a syntax plugin module which supports output in either table or plain-test style formats.
- Syntax Plugin (described below)
The syntax for this plugin is as follows and is contained in a __template.txt file which is located in the top level dwcommits directory:
~~NOCACHE~~ ~~DWCOMMITS DATABASE: dwcommits_1 TERM_1: AND_OR_TERM_2: OR TERM_2: AND_OR_AUTHOR: AND AUTHOR: DATE_1: DATE_2: BRANCH: DWCOMMITS~~
The database name is always dwcommits_<n>. The sqlite databases are numbered in sequence and are created automatically in the admin panel. You can always find out the name of a database asssociated with a particular git by clicking on the Help button at the top of the admin panel. The database name will appear at the top of the help page and can also be found by clicking on the Repos/Branches button at the top of the admin page. See the screen shot below.
The TERM fields apply to the git commit logs. You can search for two terms: TERM_1 AND/OR TERM_2. The full syntax is as follows: TERM_1 AND/OR TERM_2 AND/OR AUTHOR AND (After) DATE_1 AND (Before)DATE_2 AND (in a specified) BRANCH.
You must choose at least one search field, date, term, author, branch.
You can get a current snapshot of the files and databases you have created:
This will list the databases you have created, the paths to their local gits, and their remote urls, if set.
Auto-ID and Page Refreshing
The auto-id setting insures that your page is refreshed every time it is accessed, so that when you make changes to the database they will be immediately reflected in the output. Additionally, unless you have set the auto-id option, if you open a page to make an edit and decide against changes, you will have to make some change to the file, even if it is simply to add a blank line. Otherwise a blank page will be returned.
Web Server Access
You may be able to access and update the gits on your local server by setting the ownership of the git (both user and group) to the web server and then insuring that the web server has read/write access.
If this doesn't work for you, you might try the following, though again this might not be possible on your system: Create a separate ssh key for the web server. To do this, you will very likely need root access. The procedure is as follows:
sudo -u apache ssh-keygen -t rsa -C email@example.com
You will be asked where to store you ssh key files. On linux servers, this defaults to /var/www, which is the “home” directory for apache. Once you have done this, you can then clone repositories as the web server. For instance:
sudo -u apache git clone firstname.lastname@example.org:turnermm/fckgLite
With this in place you can use the “pull” function in the admin panel. If all else fails, you may have to update your gits from the command line, using your own identity. However, you must give the web server read/write access to the local repository nevertheless.
Top of admin panel showing help window, displaying database name, local git path, git url, and current branch.
Configuration and Settings
- Default Git: full path to directory
- Dwcommits must be pointed at a git repository on the local machine. The installation comes preset with two choices, both of them in dwcommits/db, one named “git”, the other “dokuwiki”
- Default date: month(MM), day(DD), year(YYYY)
- This is the default date from the the database will start or from which updates will be made. However, from within the admin panel, you can always set a new working date (although the default date will not change it unless you change it in the plugin's conf/metadata.php).
- Full path to your git binary, e.g. /usr/bin/git
- The git binary is not always in the web server's path and differs between Operating Systems.
- Auto ID: Part or all of a namespace or page id which will identify pages created by the syntax plugin.
- This setting will insure that these pages will always update automatically whenever the database is updated.
default.local.ini.dist in dwcommits/conf/ must be renamed
default.local.ini, if you plan to use it1). This file enables you to add additional local repositories and dates. The dates will show up as selections in the Configuration Manager and the gits in both the Configuration Manager and in the dwcommits admin panel, where you can switch between gits and create and work with the databases for the various gits.
- Fixed constant use error in helper (2018-06-05 12:45)
- Removed undefined constant warning in helper.php (2018-06-05 12:25)
- renamed default.local.ini to default.local.ini.dist to prevent overwr… (2017-04-19 02:10)
- update info (2016-07-31 12:36)
- Merge pull request #1 from splitbrain-forks/php7-signature (2016-02-02 15:47)
- Adjust method signatures to match parent (2016-02-02 13:07)
- update plugin.info (2015-12-22 02:10)
- declaration of action::register php7 compatible (2015-12-22 02:09)
Known Bugs and Issues
- This plugin has not been developed for use on Windows platforms. I would welcome input from anyone who would like to add Windows support. You can clone a copy at email@example.com:turnermm/Dokuwiki-GitHub-Plugin.git
- Search fails if branch alone is queried. FIXED
I have tested dwcommits on Centos, OS X, and Ubuntu.
- A syntax plugin which will enable Dokuwiki page-based output for queries. Currently output is restricted to the admin panel.
- Done A syntax plugin has now been added.
- A table format and 'prettier' output. Currently the output is essentially plain-text.
- Done Table formatting has also now been added