diff options
author | Joey Hess <joey@kitenet.net> | 2011-12-31 14:32:59 -0400 |
---|---|---|
committer | Joey Hess <joey@kitenet.net> | 2011-12-31 14:32:59 -0400 |
commit | 09905f66559f964ad36dc40da03d4f7f96804a91 (patch) | |
tree | b871c8a2372e6cba00aaa9b707c091f65837016b /doc | |
parent | 38195a6363e54874ce072eb2d3ced448e0b68e02 (diff) | |
parent | f0957426c586610d16ad9694e002b73324baa29a (diff) |
Merge branch 'autosync'
Diffstat (limited to 'doc')
-rw-r--r-- | doc/git-annex.mdwn | 31 | ||||
-rw-r--r-- | doc/index.mdwn | 1 | ||||
-rw-r--r-- | doc/sync.mdwn | 37 |
3 files changed, 59 insertions, 10 deletions
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn index 8096005ce..a0dd3d3f1 100644 --- a/doc/git-annex.mdwn +++ b/doc/git-annex.mdwn @@ -120,16 +120,27 @@ subdirectories). Use this to undo an unlock command if you don't want to modify the files, or have made modifications you want to discard. -* sync - - Use this command when you want to synchronize the local repository - with its default remote (typically "origin"). The sync process involves - first committing all local changes, then pulling and merging any changes - from the remote, and finally pushing the repository's state to the remote. - You can use standard git commands to do each of those steps by hand, - or if you don't want to worry about the details, you can use sync. - - Note that sync does not transfer any file contents from or to the remote. +* sync [remote ...] + + Use this command when you want to synchronize the local repository with + one or more of its remotes. You can specifiy the remotes to sync with; + the default is to sync with all remotes. Or specify --fast to sync with + the remotes with the lowest annex-cost value. + + The sync process involves first committing all local changes, then + fetching and merging the `synced/master` and the `git-annex` branch + from the remote repositories and finally pushing the changes back to + those branches on the remote repositories. You can use standard git + commands to do each of those steps by hand, or if you don't want to + worry about the details, you can use sync. + + Note that syncing with a remote will not update the remote's working + tree with changes made to the local repository. However, those changes + are pushed to the remote, so can be merged into its working tree + by running "git annex sync" on the remote. + + Note that sync does not transfer any file contents from or to the remote + repositories. * addurl [url ...] diff --git a/doc/index.mdwn b/doc/index.mdwn index 5bd42074f..e0791bf71 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 000000000..765c1e43f --- /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. |