DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:dwcommits

DWCommits Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" unknown
  • 2022-07-31 "Igor" unknown
  • 2020-07-29 "Hogfather" yes

plugin Searchable database of git/gitHub repositories

Last updated on
2018-06-05
Provides
Syntax, Admin
Repository
Source
Requires
sqlite

Tagged with database, git, github

Installation

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

About

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.

Examples/Usage

There are three components to the project, the git repository, and the sqlite database constructed from the repository, and a syntax plugin.

  1. 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.
  2. 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.
  3. 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:

{{dwcommits_INF}}

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 your_email@whatever.org
   

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 git@github.com: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.

Screen Shots

Query Results

Search for all mentions of 'plugin' since start of February 2011. Search made on Feb 21 2011.

Admin

Top of admin panel showing help window, displaying database name, local git path, git url, and current branch.

Configuration and Settings

Configuration Manager

  1. 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”
  2. 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).
  3. 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.
  4. 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.

The file 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.

Development

Change Log

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 git@github.com:turnermm/Dokuwiki-GitHub-Plugin.git
  • Search fails if branch alone is queried. FIXED

I have tested dwcommits on Centos, OS X, and Ubuntu.

ToDo/Wish List

  1. 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.
  2. A table format and 'prettier' output. Currently the output is essentially plain-text.
    • Done Table formatting has also now been added

FAQ

Sample Page from mturner.org web site

Discussion

1)
This assures that when updates are applied, your default.local.ini will not be overwritten
plugin/dwcommits.txt · Last modified: 2021-02-19 18:13 by turnermm

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki