Blame API

Last modified by Admin on 2024/05/24 01:18

cogAPI to produce blame/annotate/praise information from a history of changes
Developed by

XWiki Development Team

0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard


Since 6.2M2

Installable with the Extension Manager


This tools provides the implementation of the blame/annotate/praise algorithm. It could blame almost any list of elements by analyzing revisions of that list, starting from the most recent one.

Base API module

Expose generic blame component implementing org.xwiki.commons.blame.BlameManager role.

Like the diff module API, this API is not tied to any type so you have to first transform the datas you want to blame into lists and you will be able to link them with any kind of revision metadata. Blame will link each elements of the initial list with the revision metadata of the original revision it came from. You will have to call blame in loop with each revised list, starting from the most recent one, until all element are annotated.

public interface BlameManager
     * Annotate content with current revision based on a diff with a previous revision.
     * @param <R> type of the revision object that old metadata about the revision.
     * @param <E> type of the element to annotate (ie: String holding a line).
     * @param content the annotated content (up to the revision preceding the one given), use null to start a new
     *                blame.
     * @param revision the revision metadata to associate with the given revision.
     * @param previous the content of the previous revision to diff against the currently annotated content, use the
     *                 latest revision to start a new blame.
     * @return the updated annotated content.

   <R, E> AnnotatedContent<R, E> blame(AnnotatedContent<R, E> content, R revision, List<E> previous);

Script service

Expose more script oriented APIs of the previous modules. It also adds helpers for String based APIs using line splitters.

Here is a sample velocity snippet that proceed to a basic blame of an XWiki document at the line level. The document analyzed could be named in the URL using the ?doc= parameter.

## Use the current doc or the doc provided in argument
#if ($request.doc)
 #set ($originalDoc = $xwiki.getDocument($request.doc))
 #set ($originalDoc = $doc)
## Initialiaze the annotated content with the latest content of the document
Blame version $originalDoc.version
#set ($annotatedContent = $services.blame.blame(null, $originalDoc.getRevisionInfo($originalDoc.version), $originalDoc.content))
## Retrieve the previous version of the document
#set ($previous = $originalDoc.previousVersion)
## While ($previous && !$annotatedContent.isEntirelyAnnotated())  (limited here to 10 revisions for testing)
#foreach($i in [0..10])
 #if (!$previous || $annotatedContent.isEntirelyAnnotated())
 ## Retrieve previous content
 #set ($prevDoc = $originalDoc.getDocumentRevision($previous))
 #set ($prevInfo = $originalDoc.getRevisionInfo($previous))
 ## Blame previous revision
 #set ($annotatedContent = $services.blame.blame($annotatedContent, $prevInfo, $prevDoc.content))
 ## Retrieve the previous revision of that previous document
 #set ($previous = $prevDoc.previousVersion)
#end## While
## If the last revision is reached
#if (!$previous)
 ## Call again to resolve all remaining lines
 #set ($annotatedContent = $services.blame.blame($annotatedContent, null, ""))

#set($mesg = "Blame result")
 #set($mesg = "$mesg (Analysed up to revision $annotatedContent.oldestRevision.version)")
 #set($mesg = "$mesg (Fully analysed)")
  Complete $mesg
  Partial $mesg

|= Revision |= Data |= Author |= Line
#foreach($el in $annotatedContent)
 #set ($sourceRev = $el.revision)
 #if ($sourceRev)
   #set ($sourceVersion = $sourceRev.version)
   #set ($sourceDate = $
   #set ($sourceAuthor = $
   #set ($sourceVersion = "?.?")
   #set ($sourceDate = "?/?/?")
   #set ($sourceAuthor = "Unknown")
|$sourceVersion | $sourceDate | $sourceAuthor | {{html clean="false" wiki="false"}}$escapetool.html($el.element){{/html}}

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.


Dependencies for this extension (org.xwiki.commons:xwiki-commons-blame-api 16.3.1):

Get Connected