README.md

   1 README for Gitspread
   2 ====================
   3
   4 A project is often stored on several hosting services like
   5 [GitLab](https://gitlab.com/), [GitHub](https://github.com/),
   6 [repo.or.cz](http://repo.or.cz/) or similar for backup purposes.
   7 Ideally, all these repositories should be updated at the same time when
   8 pushing. If you’re using a slow Internet connection, like a mobile
   9 connection from a laptop, this process tends to be rather slow because
  10 the commits have to be pushed several times over a slow connection.
  11 Gitspread aims to solve this by pushing the commits once to a server
  12 with a fast connection, and pushing the commits to all the remotes from
  13 that server.
  14
  15 Setup
  16 -----
  17
  18 ### Server setup
  19
  20 - Create a directory called `$HOME/Git-spread/`.
  21 - Create a bare repository for each project under that directory:
  22   - `git init --bare $HOME/Git-spread/project.git`
  23 - Copy the `post-receive` hook script to the `hooks/` directory in the
  24   repository:
  25   - `cp -p post-receive $HOME/Git-spread/project.git/hooks/`
  26   - or manually insert the code if `hooks/post-receive` already exists.
  27 - Define all necessary remotes using SSH push URLs, for example:
  28   - `cd ~/Git-spread/project.git`
  29   - `git remote add gitlab git@gitlab.com:foo/project.git`
  30   - `git remote add github git@github.com:user/project.git`
  31 - Start a [screen](http://www.gnu.org/software/screen/) or
  32   [tmux](http://tmux.github.io/) session.
  33 - Start the `gitspreadd` daemon inside the screen/tmux session in a
  34   shell where `ssh-agent` is activated:
  35   - `ssh-agent bash`
  36   - `ssh-add ~/.ssh/id_dsa`
  37   - `gitspreadd`
  38 - Detach the screen/tmux session. `gitspreadd` is now running there even
  39   when the current shell is terminated.
  40
  41 ### Local computer
  42
  43 - Set up a git remote on the local computer which has a slow connection:
  44   - `git remote add spread user@example.org:Git-spread/project.git`
  45
  46 That’s all there is. From now on, you can push to the "spread" remote
  47 and let the remote server with a faster connection take care of
  48 spreading the commits around.
  49
  50 To stop the daemon, create a file named `stop` in the top directory.
  51 When the file is gone, the process is terminated. The PID of the current
  52 process is stored in a file named `pid`. This file is also deleted when
  53 the process terminates properly.
  54
  55 ### Directory location
  56
  57 If you don’t want to use `$HOME/Git-spread` as the location for the
  58 repositories, either set the `$GITSPREAD_REPODIR` environment variable
  59 to the preferred directory, or change the value of `$repodir` in
  60 `post-receive` and run `gitspreadd` with the `-r`/`--repodir` option.
  61 The gitspreadd daemon chooses the directory this way:
  62
  63 - Use the location specified by the `-r`/`--repodir` command line
  64   option,
  65 - otherwise use `$GITSPREAD_REPODIR` if defined,
  66 - otherwise use hardcoded value `$HOME/Git-spread`.
  67
  68 ### Configuration
  69
  70 The following option can be used in the bare repositories:
  71
  72 - gitspread.forcepush
  73   - If "true", use `-f` (`--force`) option when pushing to the remote
  74     repositories. This allows gitspreadd to push non-fast-forward
  75     branches. Use with care. Valid values: "", "false" or "true".
  76
  77 ### Environment variables
  78
  79 #### GITSPREAD_GIT
  80
  81 To use an alternative version of git, set the $GITSPREAD_GIT environment
  82 variable to the git executable to use. For example:
  83
  84     export GITSPREAD_GIT=/usr/local/bin/git
  85     ./gitspreadd
  86
  87 Source code
  88 -----------
  89
  90 Gitspread can be cloned from the following repositories:
  91
  92 - `https://gitlab.com/sunny256/gitspread.git` (Main repo)
  93 - `git://github.com/sunny256/gitspread.git`
  94 - `https://bitbucket.org/sunny256/gitspread.git`
  95 - `git://repo.or.cz/gitspread.git`
  96
  97 Git branches
  98 ------------
  99
 100 The `master` branch is considered stable and will never be rebased.
 101 Every new functionality or bug fix is created on topic branches which
 102 may be rebased now and then. All tests on `master` (executed with "make
 103 test") should succeed. If any test fails, it’s considered a bug and
 104 should be reported in the issue tracker.
 105
 106 Version compatibility
 107 ---------------------
 108
 109 To ensure compatibility between versions, the program follows the
 110 Semantic Versioning Specification described at <http://semver.org>.
 111 Using the version number `X.Y.Z` as an example:
 112
 113 - `X` is the *major version*. This number is only incremented when
 114   backwards-incompatible changes are introduced.
 115 - `Y` is the *minor version*. Increased when new backwards-compatible
 116   features are added.
 117 - `Z` is the *patch level*. Increased when new backwards-compatible
 118   bugfixes are added.
 119
 120 Gitspread works with git versions way back to `v1.5.5-rc1-12-g660b9c3`
 121 (2008-03-26).
 122
 123 Bugs and suggestions
 124 --------------------
 125
 126 Bugs and suggestions can be filed in the issue tracker at
 127 <https://gitlab.com/sunny256/gitspread/issues> .
 128
 129 License
 130 -------
 131
 132 Author: Øyvind A. Holm <sunny@sunbase.org>
 133
 134 License: GNU General Public License version 2 or later
 135
 136 This program is free software: you can redistribute it and/or modify it
 137 under the terms of the GNU General Public License as published by the
 138 Free Software Foundation, either version 2 of the License, or (at your
 139 option) any later version.
 140
 141 This program is distributed in the hope that it will be useful, but
 142 WITHOUT ANY WARRANTY; without even the implied warranty of
 143 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 144 Public License for more details.
 145
 146 You should have received a copy of the GNU General Public License along
 147 with this program. If not, see
 148 <http://www.gnu.org/licenses/gpl-2.0.txt>.
 149
 150     vim: set ft=markdown tw=72 fenc=utf8 et ts=2 sw=2 sts=2 fo=tcqw :