mirrors/git-annex
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

git-annex pull and push

Browse source 
Split out two new commands, git-annex pull and git-annex push. Those plus a
git commit are equivilant to git-annex sync.

In a sense, git-annex sync conflates 3 things, and it would have been
better to have push and pull from the beginning and not sync. Although
note that git-annex sync --content is faster than a pull followed by a
push, because it only has to walk the tree once, look at preferred
content once, etc. So there is some value in git-annex sync in speed, as
well as user convenience.

And it would be hard to split out pull and push from sync, as far as the
implementaton goes. The implementation inside sync was easy, just adjust
SyncOptions so it does the right thing.

Note that the new commands default to syncing content, unless
annex.synccontent is explicitly set to false. I'd like sync to also do
that, but that's a hard transition to make. As a start to that
transition, I added a note to git-annex-sync.mdwn that it may start to
do so in a future version of git-annex. But a real transition would
necessarily involve displaying warnings when sync is used without
--content, and time.

Sponsored-by: Kevin Mueller on Patreon
This commit is contained in:
Joey Hess 2023-05-16 16:37:30 -04:00
parent b1c396a695
commit 5df89d58c7
No known key found for this signature in database
GPG key ID: DB12DB0FF05F8F38
16 changed files with 482 additions and 210 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
CHANGELOG
View file

@ -1,5 +1,9 @@
git-annex (10.20230408) UNRELEASED; urgency=medium
* Split out two new commands, git-annex pull and git-annex push.
Those plus a git commit are equivilant to git-annex sync.
(Note that the new commands default to syncing content, unless
annex.synccontent is explicitly set to false.)
* Many commands now quote filenames that contain unusual characters the
same way that git does, to avoid exposing control characters to the terminal.
* Support core.quotePath, which can be set to false to display utf8

4
CmdLine/GitAnnex.hs
View file

@ -100,6 +100,8 @@ import qualified Command.Ungroup
import qualified Command.Config
import qualified Command.Vicfg
import qualified Command.Sync
import qualified Command.Pull
import qualified Command.Push
import qualified Command.Mirror
import qualified Command.AddUrl
import qualified Command.ImportFeed
@ -145,6 +147,8 @@ cmds testoptparser testrunner mkbenchmarkgenerator = map addGitAnnexCommonOption
, Command.Unlock.editcmd
, Command.Lock.cmd
, Command.Sync.cmd
, Command.Pull.cmd
, Command.Push.cmd
, Command.Mirror.cmd
, Command.AddUrl.cmd
, Command.ImportFeed.cmd

17
Command/Pull.hs Normal file
View file

@ -0,0 +1,17 @@
{- git-annex command
-
- Copyright 2023 Joey Hess <id@joeyh.name>
-
- Licensed under the GNU AGPL version 3 or higher.
-}
module Command.Pull (cmd) where
import Command
import Command.Sync hiding (cmd)
cmd :: Command
cmd = withAnnexOptions [jobsOption, backendOption] $
command "pull" SectionCommon
"pull content from remotes"
(paramRepeating paramRemote) (seek <--< optParser PullMode)

17
Command/Push.hs Normal file
View file

@ -0,0 +1,17 @@
{- git-annex command
-
- Copyright 2023 Joey Hess <id@joeyh.name>
-
- Licensed under the GNU AGPL version 3 or higher.
-}
module Command.Push (cmd) where
import Command
import Command.Sync hiding (cmd)
cmd :: Command
cmd = withAnnexOptions [jobsOption, backendOption] $
command "push" SectionCommon
"push content to remotes"
(paramRepeating paramRemote) (seek <--< optParser PushMode)

102
Command/Sync.hs
View file

@ -11,6 +11,7 @@
module Command.Sync (
cmd,
seek,
CurrBranch,
mergeConfig,
merge,
@ -23,8 +24,10 @@ module Command.Sync (
updateBranch,
updateBranches,
seekExportContent,
optParser,
parseUnrelatedHistoriesOption,
SyncOptions(..),
OperationMode(..),
) where
import Command
@ -73,6 +76,7 @@ import Annex.CurrentBranch
import Annex.Import
import Annex.CheckIgnore
import Types.FileMatcher
import Types.GitConfig
import qualified Database.Export as Export
import Utility.Bloom
import Utility.OptParse
@ -88,7 +92,10 @@ cmd :: Command
cmd = withAnnexOptions [jobsOption, backendOption] $
command "sync" SectionCommon
"synchronize local repository with remotes"
(paramRepeating paramRemote) (seek <--< optParser)
(paramRepeating paramRemote) (seek <--< optParser SyncMode)
data OperationMode = SyncMode | PullMode | PushMode
deriving (Eq, Show)
data SyncOptions = SyncOptions
{ syncWith :: CmdParams
@ -106,6 +113,7 @@ data SyncOptions = SyncOptions
, keyOptions :: Maybe KeyOptions
, resolveMergeOverride :: Bool
, allowUnrelatedHistories :: Bool
, operationMode :: OperationMode
}
instance Default SyncOptions where
@ -125,10 +133,11 @@ instance Default SyncOptions where
, keyOptions = Nothing
, resolveMergeOverride = False
, allowUnrelatedHistories = False
, operationMode = SyncMode
}
optParser :: CmdParamsDesc -> Parser SyncOptions
optParser desc = SyncOptions
optParser :: OperationMode -> CmdParamsDesc -> Parser SyncOptions
optParser mode desc = SyncOptions
<$> (many $ argument str
( metavar desc
<> completeRemotes
@ -136,30 +145,36 @@ optParser desc = SyncOptions
<*> switch
( long "only-annex"
<> short 'a'
<> help "only sync git-annex branch and annexed file contents"
<> help "do not operate on git branches"
)
<*> switch
( long "not-only-annex"
<> help "sync git branches as well as annex"
<> help "operate on git branches as well as annex"
)
<*> switch
<*> unlesssync False (switch
( long "commit"
<> help "commit changes to git"
)
<*> switch
))
<*> unlesssync True (switch
( long "no-commit"
<> help "avoid git commit"
)
<*> optional (strOption
))
<*> unlesssync Nothing (optional (strOption
( long "message" <> short 'm' <> metavar "MSG"
<> help "commit message"
))
<*> invertableSwitch "pull" True
( help "avoid git pulls from remotes"
)
<*> invertableSwitch "push" True
( help "avoid git pushes to remotes"
)
)))
<*> case mode of
SyncMode -> invertableSwitch "pull" True
( help "avoid git pulls from remotes"
)
PullMode -> pure True
PushMode -> pure False
<*> case mode of
SyncMode -> invertableSwitch "push" True
( help "avoid git pushes to remotes"
)
PullMode -> pure False
PushMode -> pure True
<*> switch
( long "content"
<> help "transfer annexed file contents"
@ -174,15 +189,24 @@ optParser desc = SyncOptions
<> help "transfer contents of annexed files in a given location"
<> metavar paramPath
))
<*> switch
<*> unlesssync False (switch
( long "cleanup"
<> help "remove synced/ branches from previous sync"
)
))
<*> optional parseAllOption
<*> invertableSwitch "resolvemerge" True
( help "do not automatically resolve merge conflicts"
)
<*> parseUnrelatedHistoriesOption
<*> case mode of
PushMode -> pure False
_ -> invertableSwitch "resolvemerge" True
( help "do not automatically resolve merge conflicts"
)
<*> case mode of
PushMode -> pure False
_ -> parseUnrelatedHistoriesOption
<*> pure mode
where
unlesssync v a = case mode of
SyncMode -> a
_ -> pure v
parseUnrelatedHistoriesOption :: Parser Bool
parseUnrelatedHistoriesOption =
@ -209,6 +233,7 @@ instance DeferredParseClass SyncOptions where
<*> pure (keyOptions v)
<*> pure (resolveMergeOverride v)
<*> pure (allowUnrelatedHistories v)
<*> pure (operationMode v)
seek :: SyncOptions -> CommandSeek
seek o = do
@ -241,7 +266,7 @@ seek' o = do
[ [ commit o ]
, [ withbranch (mergeLocal mc o) ]
, map (withbranch . pullRemote o mc) gitremotes
, [ mergeAnnex ]
, [ mergeAnnex ]
]
content <- shouldSyncContent o
@ -794,7 +819,11 @@ seekSyncContent o rs currbranch = do
in seekFiltered (const (pure True)) filterer $
seekHelper id ww (LsFiles.inRepoOrBranch origbranch) l
ww = WarnUnmatchLsFiles "sync"
ww = WarnUnmatchLsFiles $
case operationMode o of
SyncMode -> "sync"
PullMode -> "pull"
PushMode -> "push"
gofile bloom mvar _ f k =
go (Right bloom) mvar (AssociatedFile (Just f)) k
@ -805,7 +834,7 @@ seekSyncContent o rs currbranch = do
go ebloom mvar af k = do
let ai = OnlyActionOn k (ActionItemKey k)
startingNoMessage ai $ do
whenM (syncFile ebloom rs af k) $
whenM (syncFile o ebloom rs af k) $
void $ liftIO $ tryPutMVar mvar ()
next $ return True
@ -828,8 +857,8 @@ seekSyncContent o rs currbranch = do
-
- Returns True if any file transfers were made.
-}
syncFile :: Either (Maybe (Bloom Key)) (Key -> Annex ()) -> [Remote] -> AssociatedFile -> Key -> Annex Bool
syncFile ebloom rs af k = do
syncFile :: SyncOptions -> Either (Maybe (Bloom Key)) (Key -> Annex ()) -> [Remote] -> AssociatedFile -> Key -> Annex Bool
syncFile o ebloom rs af k = do
inhere <- inAnnex k
locs <- map Remote.uuid <$> Remote.keyPossibilities k
let (have, lack) = partition (\r -> Remote.uuid r `elem` locs) rs
@ -866,7 +895,7 @@ syncFile ebloom rs af k = do
return (got || not (null putrs))
where
wantget have inhere = allM id
[ pure (maybe True pullOption o)
[ pure (pullOption o)
, pure (not $ null have)
, pure (not inhere)
, wantGet True (Just k) af
@ -880,7 +909,7 @@ syncFile ebloom rs af k = do
next $ return True
wantput r
| pushOption o = Just False = return False
| pushOption o == False = return False
| Remote.readonly r || remoteAnnexReadOnly (Remote.gitconfig r) = return False
| isThirdPartyPopulated r = return False
| otherwise = wantGetBy True (Just k) af (Remote.uuid r)
@ -1011,8 +1040,19 @@ cleanupRemote remote (Just b, _) =
shouldSyncContent :: SyncOptions -> Annex Bool
shouldSyncContent o
| noContentOption o = pure False
-- For git-annex pull and git-annex push,
-- annex.syncontent defaults to True unless set
| operationMode o /= SyncMode = annexsynccontent True
| contentOption o || not (null (contentOfOption o)) = pure True
| otherwise = getGitConfigVal annexSyncContent <||> onlyAnnex o
-- For git-annex sync,
-- annex.syncontent defaults to False unless set
| otherwise = annexsynccontent False <||> onlyAnnex o
where
annexsynccontent d =
getGitConfigVal' annexSyncContent >>= \case
HasGlobalConfig (Just c) -> return c
HasGitConfig (Just c) -> return c
_ -> return d
notOnlyAnnex :: SyncOptions -> Annex Bool
notOnlyAnnex o = not <$> onlyAnnex o

9
Types/GitConfig.hs
View file

@ -93,7 +93,7 @@ data GitConfig = GitConfig
, annexHttpHeadersCommand :: Maybe String
, annexAutoCommit :: GlobalConfigurable Bool
, annexResolveMerge :: GlobalConfigurable Bool
, annexSyncContent :: GlobalConfigurable Bool
, annexSyncContent :: GlobalConfigurable (Maybe Bool)
, annexSyncOnlyAnnex :: GlobalConfigurable Bool
, annexDebug :: Bool
, annexDebugFilter :: Maybe String
@ -181,7 +181,7 @@ extractGitConfig configsource r = GitConfig
getmaybebool (annexConfig "autocommit")
, annexResolveMerge = configurable True $
getmaybebool (annexConfig "resolvemerge")
, annexSyncContent = configurable False $
, annexSyncContent = configurablemaybe $
getmaybebool (annexConfig "synccontent")
, annexSyncOnlyAnnex = configurable False $
getmaybebool (annexConfig "synconlyannex")
@ -287,6 +287,11 @@ extractGitConfig configsource r = GitConfig
configurable _ (Just v) = case configsource of
FromGitConfig -> HasGitConfig v
FromGlobalConfig -> HasGlobalConfig v
configurablemaybe Nothing = DefaultConfig Nothing
configurablemaybe (Just v) = case configsource of
FromGitConfig -> HasGitConfig (Just v)
FromGlobalConfig -> HasGlobalConfig (Just v)
onemegabyte = 1000000

14
doc/git-annex-config.mdwn
View file

@ -74,23 +74,27 @@ looks for these.
Set to false to prevent merge conflicts in the checked out branch
being automatically resolved by the `git-annex assitant`,
`git-annex sync`, `git-annex merge`, and the `git-annex post-receive`
hook.
`git-annex sync`, `git-annex pull`, ``git-annex merge`,
and the `git-annex post-receive` hook.
This sets a default, which can be overridden by annex.resolvemerge
in `git config`.
* `annex.synccontent`
Set to true to make git-annex sync default to syncing annexed content.
Set to true to make `git-annex sync` default to transferring
annexed content.
Set to false to prevent `git-annex pull` and `git-annex` push from
transferring annexed content.
This sets a default, which can be overridden by annex.synccontent
in `git config`.
* `annex.synconlyannex`
Set to true to make git-annex sync default to only sync the git-annex
branch and annexed content.
Set to true to make `git-annex sync`, `git-annex pull` and `git-annex
push` default to only operate on the git-annex branch and annexed content.
This sets a default, which can be overridden by annex.synconlyannex
in `git config`.

16
doc/git-annex-export.mdwn
View file

@ -52,15 +52,13 @@ paragraph do not apply. Note that dropping content from such a remote is
not supported. See individual special remotes' documentation for
details of how to enable such versioning.
The `git annex sync --content` command (and the git-annex assistant)
can also be used to export a branch to a special remote,
updating the special remote whenever the branch is changed.
To do this, you need to configure "remote.<name>.annex-tracking-branch"
to tell it what branch to track.
For example:
Commands like `git-annex push` can also be used to export a branch to a
special remote, updating the special remote whenever the branch is changed.
To do this, you need to configure "remote.<name>.annex-tracking-branch" to
tell it what branch to track. For example:
git config remote.myremote.annex-tracking-branch master
git annex sync --content
git annex push myremote
You can combine using `git annex export` to send changes to a special
remote with `git annex import` to fetch changes from a special remote.
@ -89,7 +87,7 @@ so the overwritten modification is not lost.)
* `--fast`
This sets up an export of a tree, but avoids any expensive file uploads to
the remote. You can later run `git annex sync --content` to upload
the remote. You can later run `git annex push` to upload
the files to the export.
* `--jobs=N` `-JN`
@ -162,7 +160,7 @@ export`, it will detect the export conflict, and resolve it.
[[git-annex-import]](1)
[[git-annex-sync]](1)
[[git-annex-push]](1)
[[git-annex-preferred-content]](1)

8
doc/git-annex-merge.mdwn
View file

@ -9,11 +9,11 @@ git annex merge [branch]
# DESCRIPTION
When run without any parameters, this performs the same merging (and merge
conflict resolution) that is done by the sync command, but without pushing
or pulling any data.
conflict resolution) that is done by the `git-annex pull` and `git-annex sync`
commands, but without uploading or downloading any data.
When a branch to merge is specified, this merges it, using the same merge
conflict resolution as the sync command. This is especially useful on
conflict resolution as the `git-annex pull` command. This is especially useful on
an adjusted branch, because it applies the same adjustment to the
branch before merging it.
@ -43,6 +43,8 @@ will not be done.
[[git-annex]](1)
[[git-annex-pull]](1)
[[git-annex-sync]](1)
[[git-annex-adjust]](1)

143
doc/git-annex-pull.mdwn Normal file
View file

@ -0,0 +1,143 @@
# NAME
git-annex pull - pull content from remotes
# SYNOPSIS
git annex pull `[remote ...]`
# DESCRIPTION
This command pulls content from remotes. It downloads
both git repository content, and the content of annexed files.
Like `git pull`, it merges changes into the current branch.
You can use `git pull` and `git-annex get` by hand to do the same thing as
this command, but this command handles several details, including making
sure that the git-annex branch is fetched from the remote.
Some special remotes contain a tree of files that can be imported,
and this command can be used to pull from those remotes as
well as regular git remotes. See [[git-annex-import]](1) for details
about how those special remotes work. In order for this command to import
from a special remote, `remote.<name>.annex-tracking-branch` also must
be configured, and have the same value as the currently checked out branch.
When [[git-annex-adjust]](1) has been used to check out an adjusted branch,
this command will also pull changes from the parent branch.
When [[git-annex-view]](1) has been used to check out a view branch,
this command will update the view branch to reflect any changes
to the parent branch or metadata.
Normally this tries to download the content of each annexed file,
from any remote that it's pulling from that has a copy.
To control which files it downloads, configure the preferred
content of the local repository.It will also drop files from a
remote that are not preferred content of the remote.
See [[git-annex-preferred-content]](1).
# OPTIONS
* `[remote]`
By default this command pulls from all remotes, except for remotes
that have `remote.<name>.annex-pull` (or `remote.<name>.annex-sync`)
set to false.
By specifying the names of remotes (or remote groups), you can control
which ones to pull from.
* `--fast`
Only pull with the remotes with the lowest annex-cost value configured.
When a list of remotes (or remote groups) is provided, it picks from
amoung those, otherwise it picks from amoung all remotes.
* `--only-annex` `-a`, `--not-only-annex`
Only pull the git-annex branch and annexed content from remotes,
not other git branches.
The `annex.synconlyannex` configuration can be set to true to make
this be the default behavior. To override such a setting, use
`--not-only-annex`.
When this is combined with --no-content, only the git-annex branch
will be pulled.
* `--no-content`, `--content`
Use `--no-content` to avoid downloading (and dropping)
the content of annexed files.
If you often use `--no-content`, you can set the `annex.synccontent`
configuration to false to prevent downloading content by default.
The `--content` option overrides that configuration.
* `--content-of=path` `-C path`
Only download (and drop) annexed files in the given path.
This option can be repeated multiple times with different paths.
* `--all` `-A`
Usually this command operates on annexed files in the current branch.
This option makes it operate on all available versions of all annexed files
(when preferred content settings allow).
Note that preferred content settings that use `include=` or `exclude=`
will only match the version of files currently in the work tree, but not
past versions of files.
* `--jobs=N` `-JN`
Enables parallel pulling with up to the specified number of jobs
running at once. For example: `-J10`
Setting this to "cpus" will run one job per CPU core.
(Note that git pulls are not done in parallel because that tends to be
less efficient.)
* `--allow-unrelated-histories`, `--no-allow-unrelated-histories`
Passed on to `git merge`, to control whether or not to merge
histories that do not share a common ancestor.
* `--resolvemerge`, `--no-resolvemerge`
By default, merge conflicts are automatically handled by this command.
When two conflicting versions of a file have been committed, both will
be added to the tree, under different filenames. For example, file "foo"
would be replaced with "foo.variant-A" and "foo.variant-B". (See
[[git-annex-resolvemerge]](1) for details.)
Use `--no-resolvemerge` to disable this automatic merge conflict
resolution. It can also be disabled by setting `annex.resolvemerge`
to false.
* `--backend`
Specifies which key-value backend to use when importing from a
special remote.
* Also the [[git-annex-common-options]](1) can be used.
# SEE ALSO
[[git-annex]](1)
[[git-annex-push]](1)
[[git-annex-sync]](1)
[[git-annex-preferred-content]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

127
doc/git-annex-push.mdwn Normal file
View file

@ -0,0 +1,127 @@
# NAME
git-annex push - push content to remotes
# SYNOPSIS
git annex push `[remote ...]`
# DESCRIPTION
This command pushes content to remotes. It uploads
both git repository content, and the content of annexed files.
You can use `git push` and `git-annex copy` by hand to do the same thing as
this command, but this command handles several details, including making
sure that the git-annex branch is pushed to the remote.
When using git-annex, often remotes are not bare repositories, because
it's helpful to add remotes for nearby machines that you want
to access the same annexed content. Pushing to a non-bare remote will
not normally update the remote's current branch with changes from the local
repository. (Unless the remote is configured with
receive.denyCurrentBranch=updateInstead.)
To make working with such non-bare remotes easier, this command pushes not only
local `master` to remote `master`, but also to remote `synced/master` (and
similar with other branches). When `git-annex pull` (or `git-annex sync`)
is later run on the remote, it will merge the `synced/` branches that
were pushed to it.
Some special remotes allow exporting a tree of files to them,
and this command can be used to push to those remotes as well
as regular git remotes. See [[git-annex-export]](1) for details
about how those special remotes work. In order for this command to export
to a special remote, `remote.<name>.annex-tracking-branch` also must
be configured, and have the same value as the currently checked out branch.
When [[git-annex-adjust]](1) has been used to check out an adjusted branch,
this command will propagate changes that have been made back to the
parent branch, without propagating the adjustments.
Normally this tries to upload the content of each annexed file that is
in the working tree, to any remote that it's pushing to that does not have
a copy. To control which files are uploaded to a remote, configure the preferred
content of the remote. When a file is not the preferred content of a remote,
or of the local repository, this command will try to drop the file's content.
See [[git-annex-preferred-content]](1).
# OPTIONS
* `[remote]`
By default, this command pushes to all remotes, except for remotes
that have `remote.<name>.annex-push` (or `remote.<name>.annex-sync`)
set to false or `remote.<name>.annex-readonly` set to true.
By specifying the names of remotes (or remote groups), you can control which
ones to push to.
* `--fast`
Only push to the remotes with the lowest annex-cost value configured.
When a list of remotes (or remote groups) is provided, it picks from
amoung those, otherwise it picks from amoung all remotes.
* `--only-annex` `-a`, `--not-only-annex`
Only pull the git-annex branch and annexed content from remotes,
not other git branches.
The `annex.synconlyannex` configuration can be set to true to make
this be the default behavior. To override such a setting, use
`--not-only-annex`.
When this is combined with --no-content, only the git-annex branch
will be pulled.
* `--no-content`, `--content`
Use `--no-content` to avoid uploading (and dropping) the content of annexed
files.
If you often use `--no-content`, you can set the `annex.synccontent`
configuration to false to prevent uploading content by default.
The `--content` option overrides that configuration.
* `--content-of=path` `-C path`
Only upload (or drop) annexed files in the given path.
This option can be repeated multiple times with different paths.
* `--all` `-A`
Usually this command operates on annexed files in the current branch.
This option makes it operate on all available versions of all annexed files
(when preferred content settings allow).
Note that preferred content settings that use `include=` or `exclude=`
will only match the version of files currently in the work tree, but not
past versions of files.
* `--jobs=N` `-JN`
Enables parallel pushing with up to the specified number of jobs
running at once. For example: `-J10`
Setting this to "cpus" will run one job per CPU core.
* Also the [[git-annex-common-options]](1) can be used.
# SEE ALSO
[[git-annex]](1)
[[git-annex-pull]](1)
[[git-annex-sync]](1)
[[git-annex-preferred-content]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

168
doc/git-annex-sync.mdwn
View file

@ -10,77 +10,29 @@ git annex sync `[remote ...]`
This command synchronizes the local repository with its remotes.
The sync process involves first committing any local changes to files
that have previously been added to the repository,
then fetching and merging the current branch 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.
This command first commits any local changes to files that have
previously been added to the repository. Then it does the equivilant of
[[git-annex-pull]](1) followed by [[git-annex-push]](1).
The content of annexed objects is not synced by default, but the --content
option (see below) can make that also be synchronized.
When using git-annex, often remotes are not bare repositories, because
it's helpful to add remotes for nearby machines that you want
to access the same annexed content. Syncing with a non-bare remote will
not normally update the remote's current branch with changes from the local
repository. (Unless the remote is configured with
receive.denyCurrentBranch=updateInstead.)
To make working with such non-bare remotes easier, sync pushes not only
local `master` to remote `master`, but also to remote `synced/master` (and
similar with other branches). When `git-annex sync` is later run on the
remote, it will merge the `synced/` branches that the repository has
received.
Some special remotes contain a tree of files that can be imported
and/or exported, and syncing with these remotes behaves differently.
See [[git-annex-import]](1) and [[git-annex-export]](1) for details
about how importing and exporting work; syncing with such a remote
is essentially an import followed by an export. In many cases,
importing needs to download content from the remote, and so sync will
only import when the --content option is used. (And exporting only
ever happens when --content is used.) The remote's
`remote.<name>.annex-tracking-branch` also must be configured, and
have the same value as the currently checked out branch.
When [[git-annex-adjust]](1) has been used to check out an adjusted branch,
running sync will propagate changes that have been made back to the
parent branch, without propagating the adjustments. When
[[git-annex-view]](1) has been used to check out a view branch,
running sync will update the view branch to reflect any changes
to the parent branch or metadata.
However, unlike those commands, this command does not transfer annexed
content by default. This may change in a future version of git-annex.
# OPTIONS
* `[remote]`
* `--content`, `--no-content`
By default, all remotes are synced, except for remotes that have
`remote.<name>.annex-sync` set to false. By specifying the names
of remotes (or remote groups), you can control which ones to sync with.
The --content option causes the content of annexed files
to also be pulled and pushed.
* `--fast`
The `annex.synccontent` configuration can be set to true to make
`--content` be enabled by default.
Only sync with the remotes with the lowest annex-cost value configured.
* `--content-of=path` `-C path`
When a list of remotes (or remote groups) is provided, it picks from
amoung those, otherwise it picks from amoung all remotes.
This option causes the content of annexed files in the given
path to also be pulled and pushed.
* `--only-annex` `-a`, `--not-only-annex`
Only sync the git-annex branch and annexed content with remotes,
not other git branches.
This avoids pulling and pushing other branches, and it avoids committing
any local changes. It's up to you to use regular git commands to do that.
The `annex.synconlyannex` configuration can be set to true to make
this be the default behavior of `git-annex sync`. To override such
a setting, use `--not-only-annex`.
When this is combined with --no-content, only the git-annex branch
will be synced.
This option can be repeated multiple times with different paths.
* `--commit`, `--no-commit`
@ -94,90 +46,17 @@ to the parent branch or metadata.
* `--pull`, `--no-pull`
By default, syncing pulls from remotes and imports from some special
remotes. Use --no-pull to disable all pulling.
Use this option to disable pulling.
When `remote.<name>.annex-pull` or `remote.<name>.annex-sync`
are set to false, pulling is disabled for those remotes, and using
`--pull` will not enable it.
When `remote.<name>.annex-sync` is set to false, pulling is disabled
for that remote, and using `--pull` will not enable it.
* `--push`, `--no-push`
By default, syncing pushes changes to remotes and exports to some
special remotes. Use --no-push to disable all pushing.
Use this option to disable pushing.
When `remote.<name>.annex-push` or `remote.<name>.annex-sync` are
set to false, or `remote.<name>.annex-readonly` is set to true,
pushing is disabled for those remotes, and using `--push` will not enable
it.
* `--content`, `--no-content`
Normally, syncing does not transfer the contents of annexed files.
The --content option causes the content of annexed files
to also be uploaded and downloaded as necessary, to sync the content
between the repository and its remotes.
The `annex.synccontent` configuration can be set to true to make content
be synced by default.
Normally this tries to get each annexed file that is in the working tree
and whose content the local repository does not yet have, from any remote
that it's syncing with that has a copy, and then copies each file to
every remote that it is syncing with. This behavior can be overridden by
configuring the preferred content of repositories. See
[[git-annex-preferred-content]](1).
* `--content-of=path` `-C path`
While --content operates on all annexed files,
--content-of allows limiting the transferred files to ones in a given
location.
This option can be repeated multiple times with different paths.
* `--all` `-A`
This option, when combined with `--content`, makes all available versions
of all files be synced, when preferred content settings allow.
Note that preferred content settings that use `include=` or `exclude=`
will only match the version of files currently in the work tree, but not
past versions of files.
* `--jobs=N` `-JN`
Enables parallel syncing with up to the specified number of jobs
running at once. For example: `-J10`
Setting this to "cpus" will run one job per CPU core.
When there are multiple git remotes, pushes will be made to them in
parallel. Pulls are not done in parallel because that tends to be
less efficient. When --content is synced, the files are processed
in parallel as well.
* `--allow-unrelated-histories`, `--no-allow-unrelated-histories`
Passed on to `git merge`, to control whether or not to merge
histories that do not share a common ancestor.
* `--resolvemerge`, `--no-resolvemerge`
By default, merge conflicts are automatically handled by sync. When two
conflicting versions of a file have been committed, both will be added
to the tree, under different filenames. For example, file "foo"
would be replaced with "foo.variant-A" and "foo.variant-B". (See
[[git-annex-resolvemerge]](1) for details.)
Use `--no-resolvemerge` to disable this automatic merge conflict
resolution. It can also be disabled by setting `annex.resolvemerge`
to false.
* `--backend`
Specifies which key-value backend to use when adding files,
or when importing from a special remote.
When `remote.<name>.annex-sync` is set to false, pushing is disabled for
that remote, and using `--push` will not enable it.
* `--cleanup`
@ -193,13 +72,18 @@ to the parent branch or metadata.
around and still has the change in it. Cleaning up the `synced/` branches
prevents that problem.
* Also all options supported by [[git-annex-pull]](1) and
[[git-annex-push]](1) can be used.
* Also the [[git-annex-common-options]](1) can be used.
# SEE ALSO
[[git-annex]](1)
[[git-annex-preferred-content]](1)
[[git-annex-pull]](1)
[[git-annex-push]](1)
# AUTHOR

49
doc/git-annex.mdwn
View file

@ -114,6 +114,18 @@ content from the key-value store.
See [[git-annex-lock]](1) for details.
* `pull [remote ...]`
Pull content from remotes.
See [[git-annex-pull]](1) for details.
* `push [remote ...]`
Push content to remotes.
See [[git-annex-push]](1) for details.
* `sync [remote ...]`
Synchronize local repository with remotes.
@ -706,7 +718,8 @@ content from the key-value store.
Resolves a conflicted merge, by adding both conflicting versions of the
file to the tree, using variants of their filename. This is done
automatically when using `git annex sync` or `git annex merge`.
automatically when using `git annex sync` or `git-annex pull`
or `git annex merge`.
See [[git-annex-resolvemerge]](1) for details.
@ -1163,8 +1176,8 @@ repository, using [[git-annex-config]]. See its man page for a list.)
* `annex.resolvemerge`
Set to false to prevent merge conflicts in the checked out branch
being automatically resolved by the git-annex assitant,
git-annex sync, git-annex merge,
being automatically resolved by the `git-annex assitant`,
`git-annex sync`, `git-annex pull`, `git-annex merge`,
and the git-annex post-receive hook.
To configure the behavior in all clones of the repository,
@ -1172,15 +1185,19 @@ repository, using [[git-annex-config]]. See its man page for a list.)
* `annex.synccontent`
Set to true to make git-annex sync default to syncing annexed content.
Set to true to make `git-annex sync` default to transferring
annexed content.
Set to false to prevent `git-annex pull` and `git-annex push` from
transferring annexed content.
To configure the behavior in all clones of the repository,
this can be set in [[git-annex-config]](1).
* `annex.synconlyannex`
Set to true to make git-annex sync default to only sincing the git-annex
branch and annexed content.
Set to true to make git-annex sync, git-annex pull, and git-annex push
default to only operating on the git-annex branch and annexed content.
To configure the behavior in all clones of the repository,
this can be set in [[git-annex-config]](1).
@ -1352,7 +1369,7 @@ Remotes are configured using these settings in `.git/config`.
* `remote.<name>.annex-ignore`
If set to `true`, prevents git-annex
from storing file contents on this remote by default.
from storing annexed file contents on this remote by default.
(You can still request it be used by the `--from` and `--to` options.)
This is, for example, useful if the remote is located somewhere
@ -1360,8 +1377,8 @@ Remotes are configured using these settings in `.git/config`.
Or, it could be used if the network connection between two
repositories is too slow to be used normally.
This does not prevent git-annex sync (or the git-annex assistant) from
syncing the git repository to the remote.
This does not prevent git-annex sync, git-annex pull, git-annex push,
or the git-annex assistant from operating on the git repository.
* `remote.<name>.annex-ignore-command`
@ -1371,9 +1388,8 @@ Remotes are configured using these settings in `.git/config`.
* `remote.<name>.annex-sync`
If set to `false`, prevents git-annex sync (and the git-annex assistant)
from syncing with this remote by default. However, `git annex sync <name>`
can still be used to sync with the remote.
If set to `false`, prevents git-annex sync (and git-annex pull, git-annex
sync, and the git-annex assistant) from operating on this remote by default.
* `remote.<name>.annex-sync-command`
@ -1383,13 +1399,14 @@ Remotes are configured using these settings in `.git/config`.
* `remote.<name>.annex-pull`
If set to `false`, prevents git-annex sync (and the git-annex assistant
etc) from ever pulling (or fetching) from the remote.
If set to `false`, prevents git-annex sync, git-annex pull,
(and the git-annex assistant etc) from ever pulling (or fetching)
from the remote.
* `remote.<name>.annex-push`
If set to `false`, prevents git-annex sync (and the git-annex assistant
etc) from ever pushing to the remote.
If set to `false`, prevents git-annex sync, git-annex push,
(and the git-annex assistant etc) from ever pushing to the remote.
* `remote.<name>.annex-readonly`

3
doc/todo/Having___39__git_annex_sync__39___optionally_add/comment_6_2e0ad0cdb9d813d0fbc514c1642669ca._comment
View file

@ -11,4 +11,7 @@ users want it to do more things.
It is not too late to split it up, and eventually deprecating it would be a
good path to making annex.synccontent default.
Update: Implemented `git-annex pull` and `git-annex push`, although I have
no plans yet to deprecate `git-annex sync`.
"""]]

9
doc/walkthrough/syncing.mdwn
View file

@ -23,5 +23,10 @@ repository|tips/centralized_git_repository_tutorial]]. See [[sync]] for
details.
By default `git annex sync` only syncs the metadata about your
files that is stored in git. It does not sync the contents of files, that
are managed by git-annex. To do that, you can use `git annex sync --content`
files that is stored in git. It does not sync the contents of annexed
files, that are managed by git-annex. To do that, you can use
`git annex sync --content`
There are also commands `git-annex pull` and `git-annex push` that are like
`git-annex sync`, but only transfer in one direction, do not commit, and
operate on the content of annexed files by default.

2
git-annex.cabal
View file

@ -770,6 +770,8 @@ Executable git-annex
Command.PostReceive
Command.PreCommit
Command.Proxy
Command.Pull
Command.Push
Command.ReKey
Command.ReadPresentKey
Command.RecvKey