2
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
3
<!ENTITY legal SYSTEM "legal.xml">
4
<!ENTITY appname "Back In Time">
5
<!ENTITY app "<application>&appname;</application>">
6
<!ENTITY appversion "0.9.24">
7
<!ENTITY manrevision "0.9.24">
8
<!ENTITY date "November 2008">
11
(Do not remove this comment block.)
12
Maintained by the GNOME Documentation Project
13
http://live.gnome.org/DocumentationProject
14
Template version: 3.0 beta
15
Template last modified 2006-11-21
18
<!-- =============Document Header ============================= -->
19
<article id="index" lang="C">
21
<title>&app; Manual</title>
22
<abstract role="description">
23
<para>&app; is a simple backup tool for KDE4 desktop.</para>
27
<year>2008-2009</year>
28
<holder>Oprea Dan</holder>
31
<!-- An address can be added to the publisher information. -->
32
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="legal.xml"/>
33
<!-- The file legal.xml contains link to license for the documentation,
34
and other legal stuff such as "NO WARRANTY" statement.
35
Please do not change any of this. -->
37
<!-- According to GNU FDL, revision history is mandatory if you are -->
38
<!-- modifying/reusing someone else's document. If not, you can omit it. -->
39
<!-- Remember to remove the &manrevision; entity from the revision entries other
41
<!-- than the current revision. -->
42
<!-- The revision numbering system for GNOME manuals is as follows: -->
43
<!-- * the revision number consists of two components -->
44
<!-- * the first component of the revision number reflects the release version of the GNOME desktop. -->
45
<!-- * the second component of the revision number is a decimal unit that is incremented with each revision of the manual. -->
46
<!-- For example, if the GNOME desktop release is V2.x, the first version of the manual that -->
47
<!-- is written in that desktop timeframe is V2.0, the second version of the manual is V2.1, etc. -->
48
<!-- When the desktop release version changes to V3.x, the revision number of the manual changes -->
49
<!-- to V3.0, and so on. -->
51
<releaseinfo>This manual describes version &appversion; of Back In Time.
54
<title>Feedback</title>
55
<para>To report a bug or make a suggestion regarding the &app; application or
56
this manual, send an email to:
57
<ulink url="mailto:dan@le-web.org" type="mailto">dan@le-web.org</ulink>.
59
<!-- Translators may also add here feedback address for translations -->
63
<!-- ============= Document Body ============================= -->
64
<!-- ============= Introduction ============================== -->
65
<!-- Use the Introduction section to give a brief overview of what
66
the application is and what it does. -->
67
<sect1 id="backintime-introduction">
68
<title>Introduction</title>
69
<para>&app; is a simple backup tool for Linux (this is KDE4 version). The backup is done by taking snapshots of
70
a specified set of directories.</para>
71
<para>All you have to do is:</para>
73
<listitem><para>configure where to save snapshots</para></listitem>
74
<listitem><para>cofigure what directories to backup</para></listitem>
75
<listitem><para>schedule automatic backup: disabled, every 5 minutes, every 10 minutes, every hour, every day, every week, every month</para></listitem>
77
<para>&app; acts as a "user mode" backup tool. This means that you can backup/restore only folders
78
you have write access to (actually you can backup read-only folders, but you can't restore them).</para>
79
<para>If you want to run it as root you need to use "su" (command line), "gksu" (Gnome) or "kdesudo" (KDE).</para>
80
<para>A new snapshot is created only if something changed since the last snapshot (if any).</para>
81
<para>A snapshot contains all the files from the selected directories (except for exclude patterns).
82
In order to reduce disk space it use hard-links (if possible) between snapshots for unchanged files.
83
This way a file of 10Mb, unchanged for 10 snapshots, will use only 10Mb on the disk.</para>
84
<para>When you restore a file 'A', if it already exists on the file system it will be renamed to
85
'A.backup.currentdate'.</para>
88
<!-- =========== Getting Started ============================== -->
89
<!-- Use the Getting Started section to describe the steps required
90
to start the application and to describe the user interface components
91
of the application. If there is other information that it is important
92
for readers to know before they start using the application, you should
93
also include this information here.
94
If the information about how to get started is very short, you can
95
include it in the Introduction and omit this section. -->
97
<sect1 id="backintime-getting-started">
98
<title>Getting Started</title>
99
<para>You can start &app; in the following ways:</para>
102
<term><guimenu>Applications</guimenu> menu</term>
106
<guisubmenu>System</guisubmenu>
107
<guimenuitem>Back In Time</guimenuitem>
108
</menuchoice>. </para>
112
<term>Command line</term>
114
<para>To start &app; from a command line, type the following command, then
115
press <keycap>Return</keycap>:</para>
116
<para><command>backintime [--gnome | --kde4] [ [--snapshots] path | --backup | --backup-job |
117
--snapshots-list | --snapshots-list-path | --last-snapshot | --last-snapshot-path |
118
--help | --version | --license]</command></para>
121
<para>--gnome - use GNOME GUI (if installed)</para>
124
<para>--KDE4 - use KDE4 GUI (if installed)</para>
127
<para>path - go directly to the specified file or directory.
128
If the application is already running if pass the path to the running instance.
129
If the main window is not the only window (there is already a dialog) the parameter is ignored.</para>
132
<para>-s, --snapshots - go directly to the specified file or directory and
133
show snapshots dialog.
134
If the application is already running if pass the path to the running instance.
135
If the main window is not the only window (there is already a dialog) the parameter is ignored.</para>
138
<para>-b, --backup - take a snapshot now (if needed).</para>
141
<para>--backup-job - take a snapshot (if needed) depending on schedule rules (used for cron jobs).</para>
144
<para>--snapshots-path - display the path where is saves the snapshots (if configured).</para>
147
<para>--snapshots-list - display the list of snapshot IDs.</para>
150
<para>--snapshots-list-path - display the path to snapshots.</para>
153
<para>--last-snapshot - display last snapshot ID.</para>
156
<para>--last-snapshot-path - display the path to the last snapshot.</para>
159
<para>-h, --help - display a small help and exit.</para>
162
<para>-v, --version - display the version and exit.</para>
165
<para>--license - show license and exit.</para>
172
<!-- Include any descriptions of the GUI immediately after the screenshot of the main UI, -->
173
<!-- for example, the items on the menubar and on the toolbar. This section is optional. -->
177
<!-- =========== Main Window ============================== -->
178
<sect1 id="backintime-mainwindow">
179
<title>Main Window</title>
181
<!-- ==== Figure ==== -->
182
<figure id="mainwindow-fig">
183
<title>Main Window</title>
186
<imageobject><imagedata fileref="figures/mainwindow.png" format="PNG"/></imageobject>
190
<!-- ==== End of Figure ==== -->
192
<para>The <application>Back In Time</application> main window contains the following elements:</para>
197
<term>Main toolbar</term>
198
<listitem><para>Take a new snapshot (if neccesary)</para></listitem>
199
<listitem><para>Update snapshots list</para></listitem>
200
<listitem><para>Edit selected snapshot's name</para></listitem>
201
<listitem><para>Remove selected snapshot</para></listitem>
202
<listitem><para>Settings dialog</para></listitem>
203
<listitem><para>About dialog</para></listitem>
204
<listitem><para>Help</para></listitem>
205
<listitem><para>Quit</para></listitem>
209
<term>Files toolbar</term>
210
<listitem><para>Go to parent directory</para></listitem>
211
<listitem><para>Current path</para></listitem>
212
<listitem><para>Show/Hide hidden (.*) and backup (*.~) files</para></listitem>
213
<listitem><para>Restore current file/directory</para></listitem>
214
<listitem><para>Copy current file/directory</para></listitem>
215
<listitem><para>Snapshots: show all snapshots for current the file/directory</para></listitem>
219
<term>Snapshots list</term>
221
<para>Navigate between 'now' and snapshots</para>
226
<term>Places list</term>
228
<para>Quickly navigate to special folders: home, root, bookmarks and directories to backup</para>
233
<term>Files list</term>
235
<para>Navigate through the file system at the moment specified in snapshots list.</para>
236
<para>You can sort the files (by clicking on column headers):</para>
238
<listitem>by name (folders always first)</listitem>
239
<listitem>by size</listitem>
240
<listitem>by date</listitem>
242
<para>If you click/double-click a file it will be opened using KDE4 file association. Keep in mind that snapshots are 'readonly'.</para>
243
<para>If you click/double-click a directory it will go to that directory.</para>
251
<!-- ================ Settings Dialog ================================ -->
252
<sect1 id="settingsdialog">
253
<title>Settings Dialog</title>
254
<para>When the application starts for the first time (not configured yet) this dialog is
255
displayed automaticaly.</para>
258
<guimenuitem>General</guimenuitem>
260
<!-- ==== Figure ==== -->
261
<figure id="settings-destination">
262
<title>Settings Dialog: General</title>
265
<imageobject><imagedata fileref="figures/settings_general.png" format="PNG"/></imageobject>
269
<!-- ==== End of Figure ==== -->
271
<para>Where to save snapshots.</para>
272
<para>You can schedule automatic backups:</para>
274
<listitem>disabled</listitem>
275
<listitem>every 5 minutes</listitem>
276
<listitem>every 10 minutes</listitem>
277
<listitem>every hour</listitem>
278
<listitem>every day</listitem>
279
<listitem>every week</listitem>
280
<listitem>every month</listitem>
282
<para>Automatic backup use cron jobs so cron must be running.</para>
285
<guimenuitem>Include</guimenuitem>
287
<!-- ==== Figure ==== -->
288
<figure id="settings-include">
289
<title>Settings Dialog: Include</title>
292
<imageobject><imagedata fileref="figures/settings_include.png" format="PNG"/></imageobject>
296
<!-- ==== End of Figure ==== -->
298
<para>Define the directories you want to backup.</para>
301
<guimenuitem>Exclude</guimenuitem>
303
<!-- ==== Figure ==== -->
304
<figure id="settings-exclude">
305
<title>Settings Dialog: Exclude</title>
308
<imageobject><imagedata fileref="figures/settings_exclude.png" format="PNG"/></imageobject>
312
<!-- ==== End of Figure ==== -->
314
<para>For include directories you can exclude some files and directories.</para>
315
<para>You can specifiy them directly or using patterns.</para>
318
<guimenuitem>Auto-Remove</guimenuitem>
320
<!-- ==== Figure ==== -->
321
<figure id="settings-auto-remove">
322
<title>Settings Dialog: Auto-Remove</title>
325
<imageobject><imagedata fileref="figures/settings_auto_remove.png" format="PNG"/></imageobject>
329
<!-- ==== End of Figure ==== -->
331
<para>You can automatically remove snapshots older then a specific date or if the free space is
332
less then a specified value.</para>
333
<para>Smart remove allow you to reduce the number of snapshots using the following rules:</para>
335
<listitem>keep all snapshots from today and yesterday</listitem>
336
<listitem>keep one snapshot for the last week and one for two weeks ago</listitem>
337
<listitem>keep one snapshot per month for all previous months of this year</listitem>
338
<listitem>keep one snapshot per year for all previous years</listitem>
340
<para>By default it does not remove named snapshots.</para>
343
<guimenuitem>Options</guimenuitem>
345
<!-- ==== Figure ==== -->
346
<figure id="settings-options">
347
<title>Settings Dialog: Options</title>
350
<imageobject><imagedata fileref="figures/settings_options.png" format="PNG"/></imageobject>
354
<!-- ==== End of Figure ==== -->
356
<para>Enable notifications: if there is an error while taking a snapshot it will display a notification popup.</para>
358
<!-- ==== Figure ==== -->
359
<figure id="settings-expert-options">
360
<title>Settings Dialog: Expert Options</title>
363
<imageobject><imagedata fileref="figures/settings_expert_options.png" format="PNG"/></imageobject>
367
<!-- ==== End of Figure ==== -->
369
<para>Enable schedule per included directory: if selected include list (include tab) will show a
370
second column ('Schedule'). This column allow you to specify the schedule per directory.</para>
374
<!-- ================ Snapshots Dialog ================================ -->
375
<sect1 id="snapshotsdialog">
376
<title>Snapshots Dialog</title>
377
<para>Show all snapshots for a specific file or directory.</para>
379
<!-- ==== Figure ==== -->
380
<figure id="snapshotsdialog-fig">
381
<title>Snapshots Dialog</title>
384
<imageobject><imagedata fileref="figures/snapshots.png" format="PNG"/></imageobject>
388
<!-- ==== End of Figure ==== -->
390
<para>Click/Double-click an item in the snapshots list to open it with KDE4 file associations.</para>
391
<para>When you select an item, you can:</para>
393
<listitem>Jump to: close the dialog an go to the selected snapshot in the main window</listitem>
394
<listitem>Copy the item to clipboard</listitem>
395
<listitem>Restore it (only for snapshots)</listitem>
397
<para>You can compare two different snapshots.
398
By default it use 'meld' to compare files adn directories.
399
Use diff options to change the diff command and it's parameters.</para>
402
<!-- =========== user.callback ============================== -->
403
<sect1 id="backintime-user-callback">
404
<title>user.callback</title>
405
<para>During backup process the application can call a user callback at different steps.
406
This callback is "$XDG_CONFIG_HOME/backintime/user.callback" (by default $XDG_CONFIG_HOME is ~/.config).
407
The first argument is the reason:</para>
410
<para>1 - Backup process begins.</para>
413
<para>2 - Backup process ends.</para>
416
<para>3 - A new snapshot was taken. The extra arguments are snapshot ID and snapshot path.</para>
419
<para>4 - There was an error. The second argument is the error code:</para>
422
<para>1 - The application is not configured.</para>
425
<para>2 - A "take snapshot" process is already running.</para>
428
<para>3 - Can't find snapshots directory (is it on a removable drive ?).</para>
431
<para>4 - A snapshot for "now" already exist.</para>
439
<!-- ============= Bugs ================================== -->
440
<!-- This section is optional and is commented out by default.
441
You can use it to describe known bugs and limitations of the
442
program if there are any - please be frank and list all
443
problems you know of.
445
<sect1 id="backintime-bugs">
446
<title>Known Bugs and Limitations</title>
451
<!-- ============= About ================================== -->
452
<!-- This section contains info about the program (not docs), such as
453
author's name(s), web page, license, feedback address. This
454
section is optional: primary place for this info is "About.." box of
455
the program. However, if you do wish to include this info in the
456
manual, this is the place to put it. Alternatively, you can put this information in the title page.-->
457
<sect1 id="backintime-about">
458
<title>About &app;</title>
459
<para> &app; was written by Oprea Dan
460
(<email>dan@le-web.org</email>). To find more information about
461
&app;, please visit the
462
<ulink url="http://backintime.le-web.org" type="http">Back In Time Web
463
page</ulink>. </para>
465
To report a bug or make a suggestion regarding this application or
466
this manual, sent a mail to
467
<ulink url="mailto:dan@le-web.org" type="mailto">dan@le-web.org</ulink>.
470
<para> This program is distributed under the terms of the GNU
471
General Public license version 2 as published by the Free Software
472
Foundation. A copy of this license can be found in the file
473
LICENSE included with the source code of this program. </para>