Habitat provides a convenient way for UNIX users to keep their home directories
in sync across multiple computers. Think of it like package management for home
directories. This is a package that's aimed at end users.
The easiest way to install habitat is to use::
pip install home_habitat
This will install all the dependencies for the script. Habitat also depends on
a library called ``pycrypto``, which has to be compiled using ``gcc``. On
Debian based distributions, you can run::
apt-get install python-dev
To make sure you have the proper libraries installed for ``pycrypto`` to be
compiled during the habitat installation process.
Next, you are going to need a configuration file. It's possible to run habitat
without a configuration file, but it's inconvenient and not recommended. The
basics of a configuration file look a little bit like this::
This basic configuration file sets up two things:
1. A server to connect to when you start habitat
2. A list of files to be used in the push and pull process
``default`` is a special keyword that will be used whenever you don't specify a
name for a package or server.
You should save your config file as either ``~/habitat.conf`` or
``~/.habitat.conf`` so that habitat can find it when it runs.
In addition, you will need an sftp server running on some remote computer that
you have access to. This computer will be used to store all of your packages
after you create them.
There are two operations that habitat can perform, either a push or a pull.
Pushing takes in a server name that appears in your ``habitat.conf`` file or a
connection string as well as a package name. This process will find all the
named files in your package (relative to your current package name), verify they
exist, place them all in a .tar.gz file named after the package name in your
config file, and the upload them to the server you choose by way of sftp.
For example, using the above config file, we could do the following::
In our home directory. This would take file1, file2, file3, and etc, verify
their existence, then place them in ``default.tar.gz``. This file would then be
uploaded to the default server. You would be prompted for a password, and then
the file transfer would occur, placing default.tar.gz in your home directory on
the remote server.
The next operation is a pull and is done with the following::
This command does what you would expect. It connects to the server you specify
(default in this case), grabs the package you specify (also default in this
case), and extracts it to your current directory. For our example, you would
get file1, file2, and file3 placed in your current directory after this
Beyond defaults, habitat has options, which are listed below:
* -d : turns debug mode on and off
* -c [user@host:port] : specifies a connection string to use
* -s [server] : specifies a named server (one that appears in habitat.conf) to use
In addition to accepting the push/pull argument, habitat accepts another
argument which is a named package (in habitat.conf). Given this information,
habitat will package the appropriate files. In the case of a default package
not being able to be found, habitat will ask to package all files in the current
directory as the default named package. If you choose to do so, everything will
Options in habitat.conf
First, a preferences section can be added to habitat.conf with the
debug = true|false
default_file_type="some file type" (default .tar.gz)
default_tar_name="some file name" (default is default)
Essentially, these options do what you would expect. The default file type will
specify a default file type for habitat to use when it is doing it's packaging.
Presently, habitat relies on the ``tar`` command to unpack files, so it is
not advised to change this argument until it has been tested more fully.
Default file name will change the default package to another identifier. If
this name is changed, it must also be changed in the packages section.
Next, the servers section. Each sub-heading represents the name of a server.
At minimum, any server requires a connection_string (which must be valid), and a
package_directory (the directory on the server that all packages will be
stored). An additional option, use_public_private_key, may be set to true if
you have password-less ssh set up for that server.
Finally, the packages section. At present, the only option for the packages
section is the files argument. The argument MUST start and end with triple
quotes, and be a comma delineated list of files OR directories. If ANY of the
files don't exist, the entire process will fail. Additionally, all paths are
relative from the directory that habitat was launched in. If you want absolute
paths, you are welcome to use them.
Currently, the project is in VERY early stages of development. You are likely
to encounter bugs as the project is developed. If you find any, feel free to
report them. Moreover, if you would like to contribute to this source in any
way, have at it.
TODO: Brief introduction on what you do with files - including link to relevant help section.