Metadata-Version: 1.0
Name: home_habitat
Version: 0.3.1
Summary: Synch your home directory.  Everywhere.
Home-page: https://bitbucket.org/aweidner/habitat
Author: Adam Weidner
Author-email: aweidner6993@gmail.com
License: LICENSE.txt
Description: ==========
        Habitat
        ==========
        
        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.
        
        Installation
        ============
        
        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::
        
            [servers]
                [[default]]
                    connection_string=user@host:port
                    package_directory="."
            [packages]
                [[default]]
                    files="""
                    file1,
                    file2,
                    file3,
                    etc
                    """
        
        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.
        
        Operations
        =========
        
        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::
            
            habitat push
        
        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::
        
            habitat pull
        
        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
        operation.
        
        Options
        =======
        
        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
        be packaged.
        
        Options in habitat.conf
        =======================
        
        First, a preferences section can be added to habitat.conf with the
        following arguments:
        
        [preferences]
        debug = true|false
        debug=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.
        
        Project Status
        ==============
        
        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.
        
Platform: UNKNOWN
