====== Version Control ======

**Priority: High**
**Status: Code in progress**

By versions we understand revisions of a page or revisions of the whole notebook that are stored in a revision control system. Typically such a system can deal with concurrent edits of the same document by multiple users on different machines. Some of these systems use a central server to store a master copy (e.g. CVS and Subversion)  others have a decentralized structure, tracking copies by unique IDs (e.g. Bazaar).

See [[Changes]] for more fine-grained control.

-----------

From mail:

As stated there are two components for version control: low level support in the filesystem layer of the application to use version control when creating / moving / deleting files. This will remove the need to do that manually. Also this layer should hide version control meta files from zim (if it does not use hidden files already). This part is almost done but needs more testing. Each specific version control system should have it's own subclass of zim's directory object.

The second component is the interface components in the GUI. This is my proposal of how that might work:

* "File -> Versions.." triggers a dialog that shows a list of versions, a text field and some buttons
	* The list has columns for version id, date and user name
	* Selecting a version shows the comment for that version in the text field
	* There is a toggle to switch between all versions or only for the current page
		* current page only is the default
		* current page only filters for versions that effect current page
	* There is a button to "browse" a specific revision
		* This does a checkout of the complete file tree for a specific
		* Open this as a new instance of zim in read-only mode
	* There is a button to show diff for a specific page between to revisions
		* Needs drop downs for versions - update to version selected in last and previous after clicking revision?
		* Open diff in external text editor - e.g. gvim - editor could provide highlighting for diff syntax
	* There is a button to show changes side by side between to revisions
		* Open both versions of the file in external editor - e.g. gvim -d or meld
	* There is a button to show a annotated version of the current page - optional
		* Open annotated source in external editor

See attachment for simple drawing.

{{./versions_dialog.png}}

Only other dialog that is strictly necessary is a "commit version" dialog which allows adding a comment and shows the status output of the version control system (two text fields and a "commit" button). Of course there should also be a setting to automatically commit when the notebook is closed. (Committing for each page edited seems a bad idea to me).

As a result the following methods are needed for the class implementing a specific version control system:
* list_versions(FILE) - return list of [version id, date, user, comment], FILE is optional
* get_file_diff(FILE, R1, R2) - return diff between to revisions, R1 and R2 are ids given by get_versions()
* get_file_revision(FILE, R1) - return content of FILE for a specific revision
* commit(COMMENT) - commit new version
* checkout(R1, DIR) - checkout the whole notebook dir for a specific revision to DIR
                                  - returns dir for resulting notebook (in case notebook is not version control root)
* get_file_annotated(FILE) - optional - return annotated version of FILE (e.g. bzr annotate FILE)

------------

* Properly nest doc_root and notebook dir and check if one or both is under VCS

* When the autocommit setting is used also commit when on startup there are uncommitted changes.

* Also integrate tags - allow setting tag in commit dialog - filter on tags in list - show tag in id field if this is choosen ?

* Next "Versions..." also have "Revert" action to undo all changes since last commit
	* This is an item defined in the HIG
	* If not under version control pop a dialog to explain
* The commit comment should be saved even if I don't press "commit", like a change log
	* Maybe have seperate dialog to show special page "_changes"
* More user friendly name for "commit" - "save snapshot" "save version" ?
	* "save version" would break HIG since there is no "restore version"

* Dialog for checkout ?  - add button in OpenNotebookDialog
* Dialog for merge ?? - how to handle conflicts etc. ??? - try to find external tooling
* Dialog with "send patch" and "import patch" ??

* Would be really nice to have a wizard to checkout existing branches or create new ones etc. But more of a generic tool, don't think this belongs in zim itself.
