diff --git a/README.md b/README.md new file mode 100644 index 0000000..6d5d1a5 --- /dev/null +++ b/README.md @@ -0,0 +1,134 @@ +# Borg-Qt + +Borg-Qt is a Python 3 based graphical frontend for the backup tool +[BorgBackup](https://github.com/borgbackup/borg) as its name implies it is +using the Qt5 Framework. Currently it works only on Linux. + + +## Motivation + +I think Borg is a great backup tool which should be available to many more +users. Since command line tools can be a bit scary for less experienced users I +decided to write a GUI as my "thesis" during my final semester at +the IBZ school in Aarau, Switzerland. + +## Getting Started + +These instructions will get you a copy of the project up and running on your +local machine. + +### Prerequisites + +You need to have Borg installed in order to have Borg-Qt working. You can get a +binary for your operating system here: + + +On a Debian based system you can install it by copying to `~/.local/bin/`. Borg +needs to be able to get executed by calling the command `borg`. + + cp ~/Downloads/borg-linux64 ~/.local/bin/borg + chmod +x ~/.local/bin/borg + +For other systems check their [documenation](https://borgbackup.readthedocs.io/en/stable/). + +### Installing + +Installing Borg-Qt is very simple. Download the binary for your operating +system here: + +You can then either run it by double clicking on it or by copying it to +`~/.local/bin/` like Borg. If you do that you might want to create a desktop +file for it. Puth the following code into a `borg-qt.desktop` file in +`~/.local/share/applications/`. + +``` +[Desktop Entry] +Version=1.0 +Name=Borg-Qt +Exec=/home/username/.local/bin/borg-qt +Terminal=false +Type=Application +Categories=Tools +MimeType=x-scheme-handler/tg; +``` + +Make sure the file is executable: + +``` shell +chmod +x ~/.local/share/applications/borg-qt.desktop +``` + +Now you should find Borg-Qt in your desktop's start menu. + +## Development + +To start working on Borg-Qt first clone the git repository and install +BorgBackup as described in [1.2.1]. + + git clone https://github.com/borg-qt/borg-qt.git + +Now create a virtual environment. + + cd borg-qt + python3 -m venv venv + +And activate it. + + source venv/bin/activate + +Finally you can install the depencies. + + pip3 install -r requirements.txt + +You're now all set to work on Borg-Qt. It's a good idea to run the tests before +starting. You can do this with the following command from the root of the +repository. + + make test + +To make testing the application while programming a bit easier there's a script +which reloads the application everytime a file changes in the `borg_qt` +directory. You to use it run the following command from the root of the +repository. + + ./scripts/debugging.sh + +### ToDos + +To have a look at all the planned tasks you can have a look at the planned +features here: [todos.org](docs/todos.md) + +## Used packages + +- [PyQt5](https://pyqt.readthedocs.io/en/latest/) - the GUI framework +- [PyInstaller](https://pyinstaller.readthedocs.io/en/stable/) - used for creating the binary + +## Contributing + +Everyone is welcome to submit pull requests and reports issues. +Please follow PEP8 and remove unnecessary white space when you contribute code. +And most importantly make sure that you don't break any tests and if possible +write tests for your code. + +## Versioning + +Currently there is no versioning as such. In the future a versioning scheme +based on [semantic versioning](http://semver.org/) might get used. The master +branch is considered to be the stable branch. Other branches might be highly +experimental. + +## Authors + +- Andreas Zweili - *Initial work* - [Nebucatnetzer](https://github.com/Nebucatnetzer) + +## License + +This project is licensed under the GPLv3 License - see the file +for details. + +## Acknowledgments + +- Thanks to PurpleBooth for her [README template](https://gist.github.com/PurpleBooth/109311bb0361f32d87a2). +- Thanks to [Back in Time](https://github.com/bit-team/backintime) for the inspiration. +- Thanks to [Feather Icons](https://github.com/feathericons/feather) for their great icon set. + diff --git a/README.org b/README.org deleted file mode 100644 index 6bd6212..0000000 --- a/README.org +++ /dev/null @@ -1,142 +0,0 @@ -* Borg-Qt - -Borg-Qt is a Python 3 based graphical frontend for the backup tool [[https://github.com/borgbackup/borg][BorgBackup]] -as its name implies it is using the Qt5 Framework. Currently it works only on -Linux. - -** Motivation - -I think Borg is a great backup tool which should be available to many more -users. Since command line tools can be a bit scary for less experienced users I -decided to write a GUI as my "thesis" during my final semester at the IBZ -school in Aarau, Switzerland. - -** Getting Started - -These instructions will get you a copy of the project up and running on your -local machine. - -*** Prerequisites - -You need to have Borg installed in order to have Borg-Qt working. You can get a -binary for your operating system here: -https://github.com/borgbackup/borg/releases -On a Debian based system you can install it by copying to ~~/.local/bin/~. Borg -needs to be able to get executed by calling the command ~borg~. - -#+begin_src sh -cp ~/Downloads/borg-linux64 ~/.local/bin/borg -chmod +x ~/.local/bin/borg -#+end_src -For other systems check their [[https://borgbackup.readthedocs.io/en/stable/][documenation]]. - -*** Installing - -Installing Borg-Qt is very simple. Download the binary for your operating -system here: [[https://github.com/borgqt/borg-qt/releases]] - -You can then either run it by double clicking on it or by copying it to -~~/.local/bin/~ like Borg. If you do that you might want to create a desktop -file for it. Puth the following code into a ~borg-qt.desktop~ file in -~~/.local/share/applications/~. - -#+example -[Desktop Entry] -Version=1.0 -Name=Borg-Qt -Exec=/home/username/.local/bin/borg-qt -Terminal=false -Type=Application -Categories=Tools -MimeType=x-scheme-handler/tg; -#+example - -Make sure the file is executable: -#+begin_src sh -chmod +x ~/.local/share/applications/borg-qt.desktop -#+end_src - -Now you should find Borg-Qt in your desktop's start menu. - -** Development - -To start working on Borg-Qt first clone the git repository and install -BorgBackup as described in [[Prerequisites]]. - -#+begin_src sh -git clone https://github.com/borg-qt/borg-qt.git -#+end_src - -Now create a virtual environment. - -#+begin_src sh -cd borg-qt -python3 -m venv venv -#+end_src - -And activate it. - -#+begin_src sh -source venv/bin/activate -#+end_src - -Finally you can install the depencies. - -#+begin_src sh -pip3 install -r requirements.txt -#+end_src - -You're now all set to work on Borg-Qt. It's a good idea to run the tests before -starting. You can do this with the following command from the root of the -repository. - -#+begin_src sh -make test -#+end_src - -To make testing the application while programming a bit easier there's a script -which reloads the application everytime a file changes in the ~borg_qt~ -directory. You to use it run the following command from the root of the -repository. - -#+begin_src sh -./scripts/debugging.sh -#+end_src - -*** ToDos - -To have a look at all the planned tasks you can have a look at the planned -features here: [[file:docs/todos.org][todos.org]] - -** Used packages - -- [[https://pyqt.readthedocs.io/en/latest/][PyQt5]] - the GUI framework -- [[https://pyinstaller.readthedocs.io/en/stable/][PyInstaller]] - used for creating the binary - -** Contributing - -Since I'm currently working on this as part of my thesis I won't be able to -accept any pull requests. After the 18th or March 2019 everybody is more than -invited to contribute. - -** Versioning - -Currently there is no versioning as such. In the future a versioning scheme -based on [[http://semver.org/][semantic versioning]] might get used. The master branch is considered to -be the stable branch. Other branches might be highly experimental. - -** Authors - -- Andreas Zweili - /Initial work/ - [[https://github.com/Nebucatnetzer][Nebucatnetzer]] - -** License - -This project is licensed under the GPLv3 License - see the [[file:LICENSE]] file -for details. - -** Acknowledgments - -- Thanks to PurpleBooth for her [[https://gist.github.com/PurpleBooth/109311bb0361f32d87a2][README template]]. -- Thanks to [[https://github.com/bit-team/backintime][Back in Time]] for the inspiration. -- Thanks to [[https://github.com/feathericons/feather][Feather Icons]] for their great icon set. -