diff --git a/CHANGELOG b/CHANGELOG index ec018fb3b2..317dc8ad27 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -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 diff --git a/CmdLine/GitAnnex.hs b/CmdLine/GitAnnex.hs index 7c1dec0663..5917606d64 100644 --- a/CmdLine/GitAnnex.hs +++ b/CmdLine/GitAnnex.hs @@ -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 diff --git a/Command/Pull.hs b/Command/Pull.hs new file mode 100644 index 0000000000..396bc14e54 --- /dev/null +++ b/Command/Pull.hs @@ -0,0 +1,17 @@ +{- git-annex command + - + - Copyright 2023 Joey Hess + - + - 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) diff --git a/Command/Push.hs b/Command/Push.hs new file mode 100644 index 0000000000..f4bcc651d4 --- /dev/null +++ b/Command/Push.hs @@ -0,0 +1,17 @@ +{- git-annex command + - + - Copyright 2023 Joey Hess + - + - 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) diff --git a/Command/Sync.hs b/Command/Sync.hs index def9bef8fe..c3e3473392 100644 --- a/Command/Sync.hs +++ b/Command/Sync.hs @@ -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 diff --git a/Types/GitConfig.hs b/Types/GitConfig.hs index ea7388368b..833db43c0f 100644 --- a/Types/GitConfig.hs +++ b/Types/GitConfig.hs @@ -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 diff --git a/doc/git-annex-config.mdwn b/doc/git-annex-config.mdwn index 05e510ee5d..6583cf0739 100644 --- a/doc/git-annex-config.mdwn +++ b/doc/git-annex-config.mdwn @@ -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`. diff --git a/doc/git-annex-export.mdwn b/doc/git-annex-export.mdwn index 738e7fbf3c..64770537c0 100644 --- a/doc/git-annex-export.mdwn +++ b/doc/git-annex-export.mdwn @@ -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..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..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) diff --git a/doc/git-annex-merge.mdwn b/doc/git-annex-merge.mdwn index b8331826b2..507e19ca9c 100644 --- a/doc/git-annex-merge.mdwn +++ b/doc/git-annex-merge.mdwn @@ -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) diff --git a/doc/git-annex-pull.mdwn b/doc/git-annex-pull.mdwn new file mode 100644 index 0000000000..c481ae9beb --- /dev/null +++ b/doc/git-annex-pull.mdwn @@ -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..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..annex-pull` (or `remote..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 + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-push.mdwn b/doc/git-annex-push.mdwn new file mode 100644 index 0000000000..d0d9079b59 --- /dev/null +++ b/doc/git-annex-push.mdwn @@ -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..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..annex-push` (or `remote..annex-sync`) + set to false or `remote..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 + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-sync.mdwn b/doc/git-annex-sync.mdwn index 634b110918..cdc97b0206 100644 --- a/doc/git-annex-sync.mdwn +++ b/doc/git-annex-sync.mdwn @@ -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..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..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..annex-pull` or `remote..annex-sync` - are set to false, pulling is disabled for those remotes, and using - `--pull` will not enable it. + When `remote..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..annex-push` or `remote..annex-sync` are - set to false, or `remote..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..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 diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn index 2e94f7d4b1..78427a4ba5 100644 --- a/doc/git-annex.mdwn +++ b/doc/git-annex.mdwn @@ -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..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..annex-ignore-command` @@ -1371,9 +1388,8 @@ Remotes are configured using these settings in `.git/config`. * `remote..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 ` - 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..annex-sync-command` @@ -1383,13 +1399,14 @@ Remotes are configured using these settings in `.git/config`. * `remote..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..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..annex-readonly` diff --git a/doc/todo/Having___39__git_annex_sync__39___optionally_add/comment_6_2e0ad0cdb9d813d0fbc514c1642669ca._comment b/doc/todo/Having___39__git_annex_sync__39___optionally_add/comment_6_2e0ad0cdb9d813d0fbc514c1642669ca._comment index d70ab6ef04..0d29b8139f 100644 --- a/doc/todo/Having___39__git_annex_sync__39___optionally_add/comment_6_2e0ad0cdb9d813d0fbc514c1642669ca._comment +++ b/doc/todo/Having___39__git_annex_sync__39___optionally_add/comment_6_2e0ad0cdb9d813d0fbc514c1642669ca._comment @@ -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`. """]] diff --git a/doc/walkthrough/syncing.mdwn b/doc/walkthrough/syncing.mdwn index 2947f7e077..149d6d0d0c 100644 --- a/doc/walkthrough/syncing.mdwn +++ b/doc/walkthrough/syncing.mdwn @@ -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. diff --git a/git-annex.cabal b/git-annex.cabal index 3c131d0b80..5ca5ad8e60 100644 --- a/git-annex.cabal +++ b/git-annex.cabal @@ -770,6 +770,8 @@ Executable git-annex Command.PostReceive Command.PreCommit Command.Proxy + Command.Pull + Command.Push Command.ReKey Command.ReadPresentKey Command.RecvKey