diff --git a/README.md b/README.md index cb807de..be6c9b7 100644 --- a/README.md +++ b/README.md @@ -1,107 +1,141 @@ -gcp v0.1.3 -==== -(c) Jérôme Poisson aka Goffi 2010, 2011 -(c) Jingbei Li aka petronny 2016, 2017 +gcp +=== -gcp (Goffi's cp) is a files copier. - -__This is a fork of gcp by petronny, not the original one (the `python2` branch) by Goffi. -But I'm happy to receive issues and pull requests.__ - -### LICENSE - -gcp is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -gcp is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with gcp. If not, see . +gcp (Goffi's cp) is a file copier. +License +======= -### WTF ? -gcp is a file copier, loosely inspired from cp, but with high level functionalities like: +gcp is free software: you can redistribute it and/or modify it under the terms +of the GNU General Public License as published by the Free Software Foundation, +either version 3 of the License, or (at your option) any later version. -- progression indicator -- gcp continue copying even when there is an issue: he just skip the file with problem, and go on -- journalization: gcp write what he is doing, this allow to know which files were effectively copied -- fixing names to be compatible with the target filesystem (e.g. removing incompatible chars like "?" or "*" on vfat) -- if you launch a copy when an other is already running, the files are added to the first queue, this avoid your hard drive to move its read/write head all the time -- files saving: you can keep track of files you have copied, and re-copy them later (useful when, for example, you always copy some free music to all your friends). -- gcp will be approximately option-compatible with cp (approximately because the behaviour is not exactly the same, see below) +gcp is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +PARTICULAR PURPOSE. See the GNU General Public License for more details. -**WARNING** -gcp is at an early stage of development, and really experimental: use at your own risks ! +You should have received a copy of the GNU General Public License along with +gcp. If not, see . -### How to use it ? -Pretty much like cp (see gcp --help). -Please note that the behaviour is not exactly the same as cp, even if gcp want to be option-compatible. Mainly, the destination filenames can be changed (by default, can be deactivated). -gcp doesn't implement yet all the options from cp, but it's planed. -### Journalizaion -The journal is planed to be used by gcp itself, buts remains human-readable. It is located in ~/.gcp/journal +About +===== + +gcp is a file copier, loosely inspired from cp, but with high level +functionalities such as: + +- **Progress bar.** +- gcp **keeps copying** even when there is an issue: it just skips the file, + logs an error and goes on. +- **Logging**: gcp writes what it's doing to a log file; this allows you to + know which files were effectively copied. +- **Fixing file names** to be compatible with the target filesystem (e.g. + removing incompatible chars like `?` or `*` on FAT). +- **Queue**: if you launch a copy when another copy is already running, the + files are added to the first queue; this optimizes hard drive head movement + and filesystem fragmentation. +- **Files saving**: you can keep track of the files you have copied, and copy + them again later (useful when, for example, you copy some free music to your + friends on a regular basis). +- gcp will be **approximately option-compatible with cp** (approximately + because the behaviour is not exactly the same, see below). + +**WARNING**: gcp is at a relatively early stage of development, use at your own +risks! + + +How to use it? +============== + +Pretty much like cp (see `gcp --help`). + +Please note that the behaviour is not exactly the same as cp's, even if gcp +aims to be option-compatible. Mainly, the destination filenames can be modified +(cf. the `--fs-fix` option). + +gcp doesn't implement all the options from cp yet, but it's a long-term goal. + + +Logging +======= + +The log file is aimed to be used by gcp itself, buts remains human-readable. It +is located in `~/.gcp/journal`. 3 states are used: -- OK means the file is copied and all operation were successful -- PARTIAL means the file is copied, but something went wrong (e.g. changing the permissions of the file) -- FAILED: the file is *not* copied +- **OK** means the file was copied and all operation were successful. +- **PARTIAL** means the file was copied, but something went wrong (file + permissions could not be preserved, file name had to be changed, etc.). +- **FAILED**: the file was *not* copied. -after the state, a list of things which went wront are show, separated by ", " +After the state, a list of things that went wrong is shown, separated by ", ". -### What's next ? -Several improvment are already planed +What's next? +============ + +Several improvement are already planed: - copy queue management (moving copy order) - advanced console interface -- notification (xmpp and maybe mail) when a long copy is finished -- retry for files which were not correctly copied +- notification (XMPP and maybe email) when a long copy is finished +- retry for files that were not correctly copied - badly encoded unicode filenames fix - file copy integrity check ... and other are with a "maybe" - graphic interface -- desktop (Kde, Gnome, XFCE, ...) integration -- distant copy (ftp) -- basic server mode, for copying files on network without the need of nfs or other heavy stuff - -### Credits - -A big big thank to the authors/contributors of... - -* progressbar: -gcp use ProgressBar (http://pypi.python.org/pypi/progressbar/2.2), a class coded by Nilton Volpato which allow the textual representation of progression. - -* GLib: -This heavily used library is used here for the main loop, event catching, and for DBus. Get it at http://library.gnome.org/devel/glib/ - -* DBus: -This excellent IPC is in the heart of gcp. Get more information at www.freedesktop.org/wiki/Software/dbus - -* python and its amazing standard library: -gcp was coded quickly for my own need thanks to this excellent and efficient language and its really huge standard library. Python can be download at www.python.org - -If I forgot any credit, please contact me (mail below) to fix it. - -Big thanks to contributors and package mainteners - -### Contributions -2011: Thomas Preud'homme : manpage, stat resolution fix +- desktop (Kde, Gnome, XFCE...) integration +- distant copy (FTP) +- basic server mode, for copying files on network without the need of NFS or + other heavy stuff +Credits +======= -### Contact +A big big thanks to the authors/contributors of... -You can contact me at goffi@goffi.org . -You'll find the latest version on my ftp: ftp://ftp.goffi.org/gcp, or check the wiki ( http://wiki.goffi.org/wiki/Gcp ) -Please report any bug on http://bugs.goffi.org -You can also have a look to my other main projects (and maybe to the smaller ones too ;) ): -- lm (list movie): a tool to list movies using IMdB data, loosely inspired from ls -- SàT: my main project, a jabber/XMPP client, which is a brick to many others things I have in mind +* **progressbar**: + gcp uses [ProgressBar](https://pypi.python.org/pypi/progressbar), a class + coded by Nilton Volpato that allows the textual representation of + progression. + +* **GLib**: + This heavily used library is used here for the main loop, event catching, and + for DBus. Get it at . + +* **DBus**: + This excellent IPC is ut the heart of gcp. Get more information at + . + +* **Python** and its amazing standard library: + gcp was coded quickly for my own needs thanks to this excellent and efficient + language and its really huge standard library. Python can be download at + . + +If I forgot any credit, please contact me (email below) to fix that. + +Big thanks to contributors and package maintainers. + + +Contributors +============ + +* Original author: Jérôme Poisson aka Goffi 2010-2011. +* Thomas Preud'homme 2011: manpage, stat resolution fix. +* Jingbei Li aka petronny 2016: conversion to Python3. +* Matteo Cypriani 2018: `--fs-fix` option, Python3 fixes. + + +Contact +======= + +Feedback, bug reports, patches, etc. are welcome, either by email or on the +repository's issue tracker. + +You can also have a look at Goffi's other main project, [Salut à +Toi](https://www.salut-a-toi.org/) (SàT), a Jabber/XMPP-based multi-frontend, +multipurpose communication tool. Don't hesitate to give feedback :)