User:Freddy2001/Manual:Huggle

Introduction to Huggle
Welcome to Huggle! We hope you enjoy using our software.

What is Huggle?
Huggle is a fast diff browser application intended for dealing with vandalism or other unconstructive edits on Wikimedia projects, written in C++. It was originally developed in .NET by Gurch, who is no longer active on this project. Anyone can download Huggle, but rollback permission is required to use it in unrestricted mode on English Wikipedia.

Huggle is able to load and review edits made to Wikipedia in real time, helps users identify unconstructive edits, and allows them to be reverted quickly. Various mechanisms are used to draw conclusions to whether an edit is constructive or not. It uses a semi-distributed model where edits are retrieved using a "provider" (this can be anything that is capable of distributing a stream of edit information, such as the Wikipedia API or IRC recent changes feed), pre-parsed and analyzed. This information is then shared with other anti-vandalism tools, such as ClueBot NG. Huggle also uses a number of self-learning mechanisms, including a global white-list (users that are considered trusted) and user-badness scores that are stored locally on the client's computer.

How does it work?
Huggle is connected to mediawiki through API and retrieves a list of edits that are made to a wiki in real time. These edits are then evaluated and moved to queue from which user can open them.

If edit contains some problems, it can be easily reverted, usually by a shortcut such as Q (by default this revert and warn the user who made the edit).

What are the system requirements for using Huggle?
Huggle 3 supports OSX, Linux and Windows directly. Huggle 2 only works on Windows XP, Windows Vista, and Windows 7, but there is also conditional support available for Huggle 2 via Wine on OS X and Linux (more information).

Installing Huggle
Huggle is very easy to install.


 * Step 1: (required on some wikis only) Go to Special:MyPage/huggle.css on a project where you want to use Huggle (project needs to have Huggle installed, in case you need to enable it there, please contact developers in ), insert enable:true onto the first line. This enables Huggle to run on your user account.


 * Step 2: Go to the download page and download the latest stable version for your OS.


 * Step 3: Follow instructions on download page in order to install huggle

That's it! Huggle should be fully operational.

Windows
Huggle is distributed in 3 flavors for windows:


 * MSVC-32: Windows Vista and newer 32 bit CPU
 * MSVC-64: Windows Vista and newer 64 bit CPU
 * MinGW-32: All windows versions 32 bit CPU, may run slower than MSVC version

If you are switching between MinGW and MSVC versions, you may need to purge your current huggle (uninstall and delete all leftovers from Program Files) prior installation of huggle.

Mac OS
Download .dmg file from download page, open it and copy huggle to Applications folder. Huggle should appear in dashboard immediately.

Debian
In a terminal window with superuser privileges (su or sudo) copy and paste as a single line.

To start type:

Uninstalling Huggle
To uninstall Huggle, follow these instructions. If you want to remove all of your configuration options, blank Special:Mypage/huggle.css

Windows
There should be shortcut to "uninstall huggle", using that will uninstall huggle.

There may be some leftovers in program files (folder huggle) which can be deleted.

Your personal configuration is in AppData/Local/Wikimedia/Huggle and can be also deleted if you want.

Mac OS
Just delete huggle from your applications, personal configuration is in ~/Library/Application Support/Wikimedia/Huggle

Debian / Ubuntu
You can safely remove huggle using package manager.

Compiled
When you ran "make install" file called install_manifest was generated in current folder.

It contains location of all files there were installed.

By removing these files you will uninstall huggle.

See http://www.cmake.org/Wiki/CMake_FAQ#Can_I_do_.22make_uninstall.22_with_CMake.3F for more information.

Installing huggle on custom MediaWiki installation
Huggle3 can be used with any mediawiki installation, however keep in mind that it was originally created for WMF wikis, which can be considered a large wiki farm.

For this reason huggle is designed mostly for large wiki farms and in order to run it on single small wiki, you may need to slightly tweak it.

This guide is covering installation to any wiki.

Huggle home
There is a special folder in huggle which is called huggle home.

This folder is displayed by huggle in logs when it starts, for example:

Wed Feb 11 10:01:47 2015  Home: /home/petanb/.local/share/data/Wikimedia/Huggle/

This folder contains all configuration files of huggle and we will refer to it as huggle home or $huggle_home in this manual.

It is possible to have multiple homes in order to create a number of separate huggle installations that are running isolated from each other by passing argument --chroot.

If you want to use huggle with WMF wikis and your own wiki farm, it is recommended to create 2 homes for it.

If you only want to use huggle for 1 wiki farm, you can ignore this.

Global wiki
Since huggle is designed to run on wiki farms, it requires 1 wiki that is called "global wiki" this wiki contains global configuration file that has the information about individual wikis.

In case you have only 1 wiki, you will need to make it a global wiki as well, so that you will have both global and local configuration file there.

Configuration files
 See 

Huggle is using 4 configuration files in following order:


 * $huggle_home/Configuration/huggle3.xml Local configuration on pc where it is installed - this file contains URL of global wiki
 * Huggle/Config Global configuration on global wiki which contains information about local wikis
 * Project:Huggle/Config Local configuration on wiki to which you login
 * User:$NAME/huggle3.css User configuration on local wiki

Step by step deployment on 3rd wiki farm
In this scenario we have a wiki farm with 4 wikis on domains:


 * meta.testfarm.wmflabs.org
 * wiki1.testfarm.wmflabs.org
 * wiki2.testfarm.wmflabs.org
 * wiki3.testfarm.wmflabs.org

On meta.testfarm.wmflabs.org/wiki/Huggle/Configuration we need to have following content:

enable-all:true

version:3.1.0 min-version:3.1.0

config:Project:Huggle/Config documentation:https://www.mediawiki.org/wiki/Manual:Huggle feedback:https://en.wikipedia.org/wiki/Wikipedia:Huggle/Feedback // Only if you have irc recent change stream for your wikis - this is optional // irc-server:irc.wikimedia.org // irc-server-name:irc.wikimedia.org

user-agent:Huggle/$1 http://en.wikipedia.org/wiki/Wikipedia:Huggle user-config:Special:Mypage/huggle.css user-config-hg3:Special:Mypage/huggle3.css

// URL of your whitelist server, if you don't have any, keep this commented out // whitelist-server:http://huggle.wmflabs.org/data/

In Project:Huggle/List put

Important xmlrcs_name is name of your wiki as seen by XmlRcs provider, if you don't have this provider, you can remove it from XML entry. Same applies for wl (whitelist id).

Now on each of these 3 wikis, you put this in Project:Huggle/Config.yaml

Now all you need is update the huggle local configuration, open $huggle_home/Configuration/huggle3.xml and change



to



Now you can start huggle and hit reload button. It should load a list of local wikis. Since now you should be able to use huggle on your wikis.

Note: If your wiki doesn't support HTTPS you must not check it on login form

Startup


When you first start Huggle, you should see a login screen.

At this login screen, you can select the project that you want to log on to from the drop down list.

You can also select a language other than English for Huggle to use for text prompts and buttons.

Enter your project username and password.

Huggle will then log you in, check that your account is able to use it, and read various data pages.

It is also possible to login to multiple projects within a single session.

You can do so by clicking on the Projects button, which would show a list of available projects.


 * Language — The language that objects inside Huggle will be displayed in
 * Project — Drop down list that contains all of the projects that Huggle can work with
 * Username — Your project username
 * Password — Your project password


 *  Require SSL - Force Huggle to use a secure connection to connect to the wiki.

Interface
This is Huggle's interface.



Menu toolbar
Each menu along the top has a specific function.

View details about each menu:



System menu
This is the system menu:




 * Options shows the Huggle options.


 * Reconnect IRC feed allows you to attempt to reconnect to the recent changes IRC feed. This feature is useful if changes aren't showing up.


 * My talk page (M) will display a last revision of your talk page, useful for checking of new messages.


 * Abort (ESC) kills the last query on a stack, this option may not work if you didn't enable delayed reverts.


 * Change Provider let you change the provider of edits to a different one (wiki / IRC / JSON).


 * Stop provider stops the current provider so that huggle will stop retrieving new edits. This is useful if you want to keep huggle running but you want to "pause" it.


 * Exit closes Huggle.

Tools menu
This is the Tools menu:



Page menu
The Page menu allows you to view and manipulate the current page.




 * Switch to talk page allows you to switch to the talk page of the current article.
 * View latest revision (Ctrl+V) switches to the most current revision of the page, so you can view it in its entirety.
 * Retrieve History loads more of the history of the page.
 * Show History displays the history of the selected page.
 * Edit (E) allows you to edit a page using a built-in editor.
 * Tag (G) allows you to tag a page with any number of templates.
 * Request deletion allows you to request speedy deletion, propose deletion, or tag an article for a deletion discussion.
 * Request protection brings the page to requests for page protection, where the page can be protected from editing.
 * Watch (L) adds the page to your watchlist, where you can view all changes made to the page.
 * Purge updates the copy of the article on Wikipedia's servers, forcing them to display the most recent version.
 * Mark patrolled (Ctrl+P) marks a new page as patrolled, that is; an experienced editor has looked at it and give the OK.
 * Move allows you to give the article a new title.
 * Restore this revision of the article rolls back all revisions of the page after the current revision, and sets the current revision as the live one.

Queue menu
This is the Queue menu, which relates to the Queue found on the left side of the screen.




 * Next (Space) goes to the next edit in the queue.
 * Trim allows you to trim the queue by time.
 * Clear Current (Ctrl + Space) clears the current queue.
 * Clear all clears all of the queues.
 * Manage Queues allows you to control which queues are available.

HAN menu
This is the HAN menu:



User menu
The User menu allows you to view and manipulate the current page. All of the commands affect the user listed on the bottom of the editor and article history.




 *  Increase badness score
 *  Decrease badness score of user
 *  Talk page
 *  User page
 *  Clear talk page of user
 *  Show user contributions in a browser
 *  Welcome user
 *  Block (Command-B)
 *  Report username
 *  Report user
 *  Manual template
 *  Edit user talk


 * Show user info (?) displays a window with information about the user, including blocks and warnings.
 * Ignore (I) Removes all of the user's changes from the queue>Special:MyLanguage/Manual:Huggle/Queue|queue
 * Retrieve Contributions (U) loads more of the user's contributions
 * View talk page (A) displays the user's talk page.
 * Message (N) allows you to leave a message for the user on their talk page.
 * E-mail... allows you to send an email to the user, if you have set your email in your pref>Special:Preferences|preferences
 * Warn... allows you to warn a user for vandalism. The sub-menu shows all of the options.
 * Report allows you to report the user to the administrators against vandalism page (if you select "Vandalism after final warning") or the usernames for administrator attention page (if you select "Inappropriate Username").
 * Block (CTRL + B) displays a window where you can block the user. This option is only enabled if you are an administrator.

Go to menu
The Go To menu acts as a shortcut to critical areas of Wikipedia.




 * My talk page allows you to go to your talk page on the current project.
 * My contributions allows you to go to your contributions on the current project.
 * Administrator intervention against vandalism allows you to go to the administrator intervention against vandalism page.
 * Huggle sandbox allows you go to a testing page to test Huggle.

Help menu
The help menu links you to all of the information about Huggle.




 * Contents (F1) opens up the default browser and points it to this Manual.
 * Feedback opens up the default browser and points it to Feedback, where you can give the developers bug reports and feature requests.
 * About Huggle... opens up a view with all of the contributors to Huggle. It will look like:


 * [[File:Huggle 3 About Huggle Window.JPG|

Huggle 3 About Huggle window|412x412px]]

Navigation toolbar



 * Browse back and Browse forward will go back and forward through your browsing history, rather than the history of the current page.


 * Open in browser opens whatever is being viewed in your web browser.


 * New tab opens a new tab.


 * Close tab closes the currently selected tab.


 * Previous, next, last, current revision buttons navigate through the history of the currently selected page.


 * Diff to current shows the difference between the older of the two revisions currently selected and the newest revision to the page. Its function is equivalent to the "cur" links on history pages. This can be used to check that the right revision is being reverted to when dealing with situations where multiple instances of vandalism have been partially reverted.


 * Previous, next, last, current edit buttons navigate through the contributions of the currently selected user.

Main toolbar



 * Page
 * View will view the current page.
 * Edit will open a new window containing an edit form for the current page.
 * Tag allows tagging of a page for speedy or proposed deletion, or the prepending of some other tag or tags to the page. Also supports XfD nominations
 * Delete, only available to administrators, deletes the page.
 * Watch will add the page to your Wikipedia watchlist. If the page is already on your watchlist, this button will be highlighted orange, and clicking it will remove the page from your watchlist.


 * User
 * Info will display information about the selected user, including block log, warning log and number of edits.
 * Talk will display the current user's talk page.
 * Message will prompt for a message and post it to the current user's talk page.
 * Report will prompt for an explanation and then issue a vandalism report for the current user. Note that Huggle will do this automatically when appropriate. You may also issue username reports by changing "Report to:". If you are an administrator, this button becomes Block, which will prompt for block summary, time and options and then block the current user.

Actions toolbar



 * Page
 * View will view the current page.
 * Edit will open a new window containing an edit form for the current page.
 * Tag allows tagging of a page for speedy or proposed deletion, or the prepending of some other tag or tags to the page. Also supports XfD nominations
 * Delete, only available to administrators, deletes the page.
 * Watch will add the page to your Wikipedia watchlist. If the page is already on your watchlist, this button will be highlighted orange, and clicking it will remove the page from your watchlist.


 * User
 * Info will display information about the selected user, including block log, warning log and number of edits.
 * Talk will display the current user's talk page.
 * Message will prompt for a message and post it to the current user's talk page.
 * Report will prompt for an explanation and then issue a vandalism report for the current user. Note that Huggle will do this automatically when appropriate. You may also issue username reports by changing "Report to:". If you are an administrator, this button becomes Block, which will prompt for block summary, time and options and then block the current user.

Page and editor
The area on top shows the User / Editor Name and the Page Name:



Queue
The queue shows all of the current changes to the wiki.



The queue has several different modes of operation:


 * All Edits – Displays every edit as it occurs. The queue is in chronological order.
 * All New Pages – Displays pages as they're created.
 * Assisted Edits – Only shows edits made with an automated tool.
 * Candidates for speedy deletion – Only shows edits made to pages that are tagged for speedy deletion


 * Filtered Edits – Automatically removed the edits from bots and other trusted users, then sorts the results by the probability that an edit is vandalism.
 * Filtered new pages – The same as Filtered Edits, but only displays new pages.
 * Huggle edits – Only shows edits made with Huggle.
 * My edits – Shows the edit's you've made.
 * Add... – Allows you to define your own queues.

History of your changes
This area on the left shows all the changes that you made during this huggle session by huggle only. Your edits made by different tools or instances of huggle are not shown in this window.



Log
The log located at the bottom of the Huggle interface tells you what is going on.




 * Red text — Edits or processes in the queue
 * Black text — Edits or processes that have been carried out

Reverts per minute log


In the lower left hand corner of the interface, you will find the statistics of the current editing session.

The color of the text indicates the current volume of vandalism reverts:


 * {| class="wikitable"


 * Green || Low
 * Blue || Low-moderate
 * Black || Moderate (average)
 * Red || High
 * }
 * Black || Moderate (average)
 * Red || High
 * }
 * }

Diff view
Huggle's diff view uses the standard mw>Special:MyLanguage/MediaWiki|MediaWiki view, in that changes are highlighted in green or yellow, additions have a little plus sign ( + ) to the left of them, and removals are marked in red font.



For full details about diff views, please read this page.

Article history
The area in the top right shows information about the page and editor history.



Along the top row is the page name (the drop down menu lists the ten most recent pages you were on) and then shows the history of the page in icons. Clicking on an icon will bring up the associated changed in diffview>Special:MyLanguage/Manual:Huggle/Diff View|the diff view. By default, only a small amount of history is loaded. Clicking on History will load more.

The user line acts much in the same way, except that it shows all of the recent changes by the user, to any page.

Keyboard shortcuts
Operation is quicker when you use keyboard shortcuts. Note that giving focus to the browser window prevents shortcuts working; click any button to take focus from the browser window. Keyboard shortcuts may be customized; go to System -> Options... and select the Keyboard tab.

Main

 * Space – Show next diff
 * Q – Revert and warn
 * R – Revert
 * Y – Revert with custom summary


 * T – Post template message
 * W – Warn
 * Escape – Cancel

Navigation

 * [ – Browse back
 * ] – Browse forward
 * Z – Previous revision
 * X – Next revision
 * C – Current revision


 * Ctrl + Z – Previous contribution
 * Ctrl + X – Next contribution
 * Ctrl + C – Latest contribution
 * D – Show diff to current revision
 * O – Open page in external browser


 * + – New tab
 *  –  – Close tab
 * Tab – Next tab
 * Shift + Tab – Previous tab

Page

 * V – View page (this revision)
 * Ctrl + V – View page (latest revision)
 * E – Edit page
 * G – Tag page
 * S – Tag page for deletion


 * Ctrl + S – Nominate page for deletion
 * P – Prod tag page
 * Ctrl + P – Mark as patrolled
 * Ctrl + D – Delete page
 * L – Watch / Unwatch page

User

 * I – Ignore user
 * Ctrl + I – Unignore user
 * / (?) - Show user info


 * A – View user talk page
 * N – Message user
 * B – Report user / Block user

Other

 * H – Retrieve history for current page
 * U – Retrieve contributions for current user
 * K – Toggle "show new edits"
 * M – Show new messages
 * Ctrl + Space – Clear queue

List builder feature
The list builder enables you to build custom lists for Huggle to work through using a variety of different sources.



On the left:
 * Add — Adds a new list to the list builder
 * Delete — Deletes the selected list from the list builder
 * Copy — Copies the selected list
 * Rename — Renames the selected list

Watching your watchlist (Huggle version 0.9.6)
To watch your own watchlist: Remember, queues are not saved between sessions and your watchlist will not update until one of the watched pages is changed.
 * 1) Close Huggle, open your own watchlist here and make any changes you desire, and restart Huggle. (Note: To watch an entire category of pages, export the page names via Special:Export and paste the names into your watchlist.)
 * 2) Select menu Queue-->Manage Queues and then the Page title tab.
 * 3) Under Queues, add a new queue named Watchlist.
 * 4) Under Queue type, select the radio button for Dynamic list.
 * 5) Select the List source tab.
 * 6) On the Source type dropdown, select Watchlist.
 * 7) Do not select the checkbox for re-adding pages that were previously removed. As of this writing, the writer's experience is that doing so will cause Huggle to return an error every time a new page is selected.
 * 8) Press OK and test.

Also Note: Watchlist watching does not yet appear to be enabled.

Page title filters (Huggle version 0.9.6)
If you wish to limit your search to pages having a specific word in the page title, use page title filters. The field label does say, "Title matches regular expression:" but try just entering your keyword first. If you're interested in searching on just one word, formal regex syntax does not appear to be necessary.

Requests view
The requests form shows all of the requests that have been made by Huggle. The requests that are at different stages are shown in different colors.




 * Cancel all — Cancels all the current pending requests
 * Clear — Clears the list of requests
 * OK — Exits the window and goes back to the main interface

Statistics view
The statistics form shows:
 * The length of time you have been in your current session
 * Number of edits, assisted edits, Huggle edits, reverts, warnings, reports, tags, notifications, blocks, deletions and protections



Closing Huggle
The closing window appears when Huggle is closing. This goes through the stages of updating the whitelist (if needed) and updating the user config (if needed)