From b538f45fafdf161c24f07562ac1bd73f1476ace9 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Fri, 30 Dec 2011 20:02:55 -0400 Subject: [PATCH] add a sync page documenting sync in detail --- doc/index.mdwn | 1 + doc/sync.mdwn | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 38 insertions(+) create mode 100644 doc/sync.mdwn diff --git a/doc/index.mdwn b/doc/index.mdwn index 5bd42074f5..e0791bf71a 100644 --- a/doc/index.mdwn +++ b/doc/index.mdwn @@ -45,6 +45,7 @@ files with git. * [[git-annex man page|git-annex]] * [[key-value backends|backends]] for data storage * [[special_remotes]] (including [[special_remotes/S3]] and [[special_remotes/bup]]) +* [[sync]] * [[encryption]] * [[bare_repositories]] * [[internals]] diff --git a/doc/sync.mdwn b/doc/sync.mdwn new file mode 100644 index 0000000000..765c1e43fd --- /dev/null +++ b/doc/sync.mdwn @@ -0,0 +1,37 @@ +The `git annex sync` command provides an easy way to keep several +repositories in sync. + +Often git is used in a centralized fashion with a central bare repositry +which changes are pulled and pushed to using normal git commands. +That works fine, if you don't mind having a central repository. + +But it can be harder to use git in a fully decentralized fashion, with no +central repository and still keep repositories in sync with one another. +You have to remember to pull from each remote, and merge the appopriate +branch after pulling. It's difficult to *push* to a remote, since git does +not allow pushes into the currently checked out branch. + +`git annex sync` makes it easier using a scheme devised by Joachim +Breitner. The idea is to have a branch `synced/master` (actually, +`synced/$currentbranch`), that is never directly checked out, and serves +as a drop-point for other repositories to use to push changes. + +When you run `git annex sync`, it merges the `synced/master` branch +into `master`, receiving anything that's been pushed to it. Then it +fetches from each remote, and merges in any changes that have been made +to the remotes too. Finally, it updates `synced/master` to reflect the new +state of `master`, and pushes it out to each of the remotes. + +This way, changes propigate around between repositories as `git annex sync` +is run on each of them. Every repository does not need to be able to talk +to every other repository; as long as the graph of repositories is +connected, and `git annex sync` is run from time to time on each, a given +change, made anywhere, will eventually reach every other repository. + +The workflow for using `git annex sync` is simple: + +* Make some changes to files in the repository, using `git-annex`, + or anything else. +* Run `git annex sync` to save the changes. +* Next time you're working on a different clone of that repository, + run `git annex sync` to update it.