The task of Pootle FS is to keep the filesystem and Pootle in sync. There are scenarios where items are not in sync and Pootle FS requires your intervention, these are the commands you need to bring things back into sync and to resolve conflicts.
To clarify the terminology that we use in Pootle FS:
file
- a translation file on diskstore
- a translation file in the Pootle databaseFiles and stores are usually associated and thus we are able to keep them synchronised. But there might be files with no store (the store for a new file has not yet been created in the Pootle database), and stores with no file (the file has been removed from the filesystem).
Pootle FS works in two stages:
Files that have not being synced yet are untracked, and thus they need to be explicitly staged. Files previously synced are tracked, and thus automatically staged when any changes. In case of conflict (changes both in disk and Pootle) it is also necessary to manually stage these to resolve which version should prevail.
When staging changed items it is possible to specify specific stores or files,
or groups of them using the -P
and -p
options. It is also possible to
limit which staged actions are performed by using these same options on the
sync
command.
When a store and corresponding file have been synced previously, they are automatically staged for syncing if either changes.
If both have changed then we will be required to specify how to resolve the conflicts.
To re-sync stores and files just run:
(env) $ pootle fs sync MYPROJECT
When new files appear on the filesystem that we want to bring into Pootle we
use fetch
:
(env) $ pootle fs fetch MYPROJECT
(env) $ pootle fs sync MYPROJECT
Where fetch
will stage the previously untracked files, and
sync
will synchronize, pulling the translations in the file into the
Pootle database.
Following this the file and store are now tracked.
When new stores have appeared on Pootle that we want to push to the filesystem
we use add
:
(env) $ pootle fs add MYPROJECT
(env) $ pootle fs sync MYPROJECT
Where add
will stage the previously untracked store, and
sync
will synchronize, pushing the translations in the Pootle store
onto the filesystem.
A store or file can be missing from Pootle or the filesystem because it has
been removed, we use rm
to remove such files and stores:
(env) $ pootle fs rm MYPROJECT
(env) $ pootle fs sync MYPROJECT
This will remove the store or file, depending on whether it is the file or store that remains.
Following this there is no such file or store on the filesystem or on Pootle.
Conflicts can occur if a tracked Pootle store and its corresponding file have both changed. They can also arise if a new Pootle store is added and a matching file has been added in the filesystem simultaneously.
There are four possible ways to resolve such conflicts:
The merge options are most useful where you need translators to resolve the conflict.
You want to keep the version that is currently on the filesystem, discarding all changes in Pootle:
(env) $ pootle fs fetch --force MYPROJECT
(env) $ pootle fs sync MYPROJECT
You wish to keep the version that is currently in Pootle, discarding all changes in the filesystem:
(env) $ pootle fs add --force MYPROJECT
(env) $ pootle fs sync MYPROJECT
To retain all translation and allow translators to resolve conflicts use
merge
. This will merge any non-conflicting units and convert
conflicts into suggestions, by default we use filesystem translations:
(env) $ pootle fs merge MYPROJECT
(env) $ pootle fs sync MYPROJECT
The result is that all non-conflicting units have been synchronised. For any unit where both the store unit and file unit changed the translation is set to the file unit translation with the store unit translation converted into a suggestion. You can now review these suggestions to resolve the conflicts.
To retain all translation and allow translators to resolve conflicts use
merge
. This will merge any non-conflicting units and convert
conflicts into suggestions, the --pootle-wins
option ensures that we use Pootle translations and convert filesystem
translations into suggestions:
(env) $ pootle fs merge --pootle-wins MYPROJECT
(env) $ pootle fs sync MYPROJECT