diff --git a/Annex/AdjustedBranch/Merge.hs b/Annex/AdjustedBranch/Merge.hs --- a/Annex/AdjustedBranch/Merge.hs +++ b/Annex/AdjustedBranch/Merge.hs @@ -80,8 +80,9 @@ -- Copy in refs and packed-refs, to work -- around bug in git 2.13.0, which -- causes it not to look in GIT_DIR for refs. - refs <- liftIO $ dirContentsRecursive $ - git_dir' "refs" + refs <- liftIO $ emptyWhenDoesNotExist $ + dirContentsRecursive $ + git_dir' "refs" let refs' = (git_dir' "packed-refs") : refs liftIO $ forM_ refs' $ \src -> do let src' = toRawFilePath src diff --git a/Annex/Branch.hs b/Annex/Branch.hs --- a/Annex/Branch.hs +++ b/Annex/Branch.hs @@ -183,23 +183,24 @@ branchref <- getBranch ignoredrefs <- getIgnoredRefs let unignoredrefs = excludeset ignoredrefs pairs - tomerge <- if null unignoredrefs - then return [] + (tomerge, notnewer) <- if null unignoredrefs + then return ([], []) else do mergedrefs <- getMergedRefs - filterM isnewer (excludeset mergedrefs unignoredrefs) + partitionM isnewer $ + excludeset mergedrefs unignoredrefs {- In a read-only repository, catching permission denied lets - query operations still work, although they will need to do - additional work since the refs are not merged. -} catchPermissionDenied (const (updatefailedperms tomerge)) - (go branchref tomerge) + (go branchref tomerge notnewer) where excludeset s = filter (\(r, _) -> S.notMember r s) isnewer (r, _) = inRepo $ Git.Branch.changed fullname r - go branchref tomerge = do + go branchref tomerge notnewer = do dirty <- journalDirty gitAnnexJournalDir journalcleaned <- if null tomerge {- Even when no refs need to be merged, the index @@ -229,6 +230,7 @@ journalclean <- if journalcleaned then not <$> privateUUIDsKnown else pure False + addMergedRefs notnewer return $ UpdateMade { refsWereMerged = not (null tomerge) , journalClean = journalclean diff --git a/Annex/Tmp.hs b/Annex/Tmp.hs --- a/Annex/Tmp.hs +++ b/Annex/Tmp.hs @@ -61,7 +61,8 @@ tmpdir <- fromRawFilePath <$> fromRepo gitAnnexTmpOtherDir void $ liftIO $ tryIO $ removeDirectoryRecursive tmpdir oldtmp <- fromRawFilePath <$> fromRepo gitAnnexTmpOtherDirOld - liftIO $ mapM_ cleanold =<< dirContentsRecursive oldtmp + liftIO $ mapM_ cleanold + =<< emptyWhenDoesNotExist (dirContentsRecursive oldtmp) liftIO $ void $ tryIO $ removeDirectory oldtmp -- when empty where cleanold f = do diff --git a/Annex/Url.hs b/Annex/Url.hs --- a/Annex/Url.hs +++ b/Annex/Url.hs @@ -34,6 +34,7 @@ import Annex.Common import qualified Annex import qualified Utility.Url as U +import qualified Utility.Url.Parse as U import Utility.Hash (IncrementalVerifier) import Utility.IPAddress import Network.HTTP.Client.Restricted @@ -82,7 +83,7 @@ ["all"] -> do curlopts <- map Param . annexWebOptions <$> Annex.getGitConfig allowedurlschemes <- annexAllowedUrlSchemes <$> Annex.getGitConfig - let urldownloader = if null curlopts && not (any (`S.member` U.conduitUrlSchemes) allowedurlschemes) + let urldownloader = if null curlopts && not (any (`S.notMember` U.conduitUrlSchemes) allowedurlschemes) then U.DownloadWithConduit $ U.DownloadWithCurlRestricted mempty else U.DownloadWithCurl curlopts diff --git a/Assistant/DaemonStatus.hs b/Assistant/DaemonStatus.hs --- a/Assistant/DaemonStatus.hs +++ b/Assistant/DaemonStatus.hs @@ -13,6 +13,7 @@ import Assistant.Alert.Utility import Utility.Tmp import Utility.NotificationBroadcaster +import Types.Availability import Types.Transfer import Logs.Transfer import Logs.Trust @@ -59,6 +60,7 @@ let (exportremotes, nonexportremotes) = partition (exportTree . Remote.config) contentremotes let isimport r = importTree (Remote.config r) || Remote.thirdPartyPopulated (Remote.remotetype r) let dataremotes = filter (not . isimport) nonexportremotes + tocloud <- anyM iscloud contentremotes return $ \dstatus -> dstatus { syncRemotes = syncable @@ -66,10 +68,14 @@ , syncDataRemotes = dataremotes , exportRemotes = exportremotes , downloadRemotes = contentremotes - , syncingToCloudRemote = any iscloud contentremotes + , syncingToCloudRemote = tocloud } where - iscloud r = not (Remote.readonly r) && Remote.availability r == Remote.GloballyAvailable + iscloud r + | Remote.readonly r = pure False + | otherwise = tryNonAsync (Remote.availability r) >>= return . \case + Right GloballyAvailable -> True + _ -> False {- Updates the syncRemotes list from the list of all remotes in Annex state. -} updateSyncRemotes :: Assistant () diff --git a/Assistant/Repair.hs b/Assistant/Repair.hs --- a/Assistant/Repair.hs +++ b/Assistant/Repair.hs @@ -127,7 +127,8 @@ -} repairStaleGitLocks :: Git.Repo -> Assistant Bool repairStaleGitLocks r = do - lockfiles <- liftIO $ filter islock <$> findgitfiles r + lockfiles <- liftIO $ filter islock + <$> emptyWhenDoesNotExist (findgitfiles r) repairStaleLocks lockfiles return $ not $ null lockfiles where diff --git a/Assistant/Restart.hs b/Assistant/Restart.hs --- a/Assistant/Restart.hs +++ b/Assistant/Restart.hs @@ -16,6 +16,7 @@ import Utility.ThreadScheduler import Utility.NotificationBroadcaster import Utility.Url +import Utility.Url.Parse import Utility.PID import qualified Utility.RawFilePath as R import qualified Git.Construct diff --git a/Assistant/Sync.hs b/Assistant/Sync.hs --- a/Assistant/Sync.hs +++ b/Assistant/Sync.hs @@ -59,11 +59,11 @@ reconnectRemotes :: [Remote] -> Assistant () reconnectRemotes [] = recordExportCommit reconnectRemotes rs = void $ do - rs' <- liftIO $ filterM (Remote.checkAvailable True) rs + rs' <- liftAnnex $ filterM (Remote.checkAvailable True) rs unless (null rs') $ do failedrs <- syncAction rs' (const go) forM_ failedrs $ \r -> - whenM (liftIO $ Remote.checkAvailable False r) $ + whenM (liftAnnex $ Remote.checkAvailable False r) $ repoHasProblem (Remote.uuid r) (syncRemote r) mapM_ signal $ filter (`notElem` failedrs) rs' recordExportCommit diff --git a/Assistant/Threads/Exporter.hs b/Assistant/Threads/Exporter.hs --- a/Assistant/Threads/Exporter.hs +++ b/Assistant/Threads/Exporter.hs @@ -51,7 +51,7 @@ - to avoid ugly messages when a removable drive is not attached. -} exportTargets :: Assistant [Remote] -exportTargets = liftIO . filterM (Remote.checkAvailable True) +exportTargets = liftAnnex . filterM (Remote.checkAvailable True) =<< candidates <$> getDaemonStatus where candidates = filter (not . Remote.readonly) . exportRemotes diff --git a/Assistant/Threads/ProblemFixer.hs b/Assistant/Threads/ProblemFixer.hs --- a/Assistant/Threads/ProblemFixer.hs +++ b/Assistant/Threads/ProblemFixer.hs @@ -56,7 +56,7 @@ handleRemoteProblem' :: Git.Repo -> UrlRenderer -> Remote -> Assistant Bool handleRemoteProblem' repo urlrenderer rmt | Git.repoIsLocal repo && not (Git.repoIsLocalUnknown repo) = - ifM (liftIO $ checkAvailable True rmt) + ifM (liftAnnex $ checkAvailable True rmt) ( do fixedlocks <- repairStaleGitLocks repo fsckresults <- showFscking urlrenderer (Just rmt) $ tryNonAsync $ diff --git a/Assistant/Threads/Pusher.hs b/Assistant/Threads/Pusher.hs --- a/Assistant/Threads/Pusher.hs +++ b/Assistant/Threads/Pusher.hs @@ -44,7 +44,7 @@ - to avoid ugly messages when a removable drive is not attached. -} pushTargets :: Assistant [Remote] -pushTargets = liftIO . filterM (Remote.checkAvailable True) +pushTargets = liftAnnex . filterM (Remote.checkAvailable True) =<< candidates <$> getDaemonStatus where candidates = filter (not . Remote.readonly) . syncGitRemotes diff --git a/Assistant/WebApp/Configurators/WebDAV.hs b/Assistant/WebApp/Configurators/WebDAV.hs --- a/Assistant/WebApp/Configurators/WebDAV.hs +++ b/Assistant/WebApp/Configurators/WebDAV.hs @@ -22,7 +22,7 @@ import Types.GitConfig import Annex.SpecialRemote.Config import Types.ProposedAccepted -import Utility.Url +import Utility.Url.Parse import qualified Data.Map as M import qualified Data.Text as T diff --git a/Build/BundledPrograms.hs b/Build/BundledPrograms.hs --- a/Build/BundledPrograms.hs +++ b/Build/BundledPrograms.hs @@ -63,14 +63,11 @@ , Just "sh" -- used by git-annex when available , Just "uname" + -- Included in git for Windows + , Just "cp" #endif , BuildInfo.lsof , BuildInfo.gcrypt -#ifndef mingw32_HOST_OS - -- These utilities are included in git for Windows - , ifset BuildInfo.curl "curl" - , Just "cp" -#endif #ifdef linux_HOST_OS -- used to unpack the tarball when upgrading , Just "gunzip" @@ -82,11 +79,6 @@ -- we rely on the system's own version, which may better match -- its kernel, and avoid using them if not available. ] - where -#ifndef mingw32_HOST_OS - ifset True s = Just s - ifset False _ = Nothing -#endif magicDLLs :: [FilePath] #ifdef mingw32_HOST_OS diff --git a/Build/mdwn2man b/Build/mdwn2man deleted file mode 100644 --- a/Build/mdwn2man +++ /dev/null @@ -1,58 +0,0 @@ -#!/usr/bin/env perl -# Warning: hack - -my $prog=shift; -my $section=shift; - -print ".TH $prog $section\n"; - -while (<>) { - s{(\\?)\[\[([^:\s\|\]]+)(\|[^\s\]]+)?\]\]}{$1 ? "[[$2]]" : $2}eg; - s/\`([^\`]*)\`/\\fB$1\\fP/g; - s/\`//g; - s/^ *\./\\&./g; - if (/^#\s/) { - s/^#\s/.SH /; - <>; # blank; - } - s/^[ \n]+//; - s/^\t/ /; - s/-/\\-/g; - s/git\\-annex/git-annex/g; - s/^Warning:.*mdwn2man.*//g; - s/^$/.PP\n/; - s/^\*\s+(.*)/.IP "$1"/; - s/\\$/\\\\/; - next if $_ eq ".PP\n" && $skippara; - if (/^.IP /) { - $inlist=1; - $spippara=0; - } - elsif (/^.SH/) { - $skippara=0; - $inlist=0; - } - elsif (/^\./) { - $skippara=1; - } - else { - $skippara=0; - } - if ($inlist && $_ eq ".PP\n") { - $_=".IP\n"; - } - - if ($inNAME) { - # make lexgrog happy - s/^git-annex (\w)/git-annex-$1/; - } - if ($_ eq ".SH NAME\n") { - $inNAME=1; - } - else { - $inNAME=0; - } - s/\\"/\\\\"/g; # hack for git-annex-shell's quotes around SSH_ORIGINAL_COMMAND - - print $_; -} diff --git a/CHANGELOG b/CHANGELOG --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,29 @@ +git-annex (10.20230828) upstream; urgency=medium + + * oldkeys: New command that lists the keys used by old versions of a file. + * Fix behavior of onlyingroup. + * info: Added --dead-repositories option. + * Significant startup speed increase by avoiding repeatedly checking + if some remote git-annex branch refs need to be merged. + * Fix behavior when importing a tree from a directory remote when the + directory does not exist. An empty tree was imported, rather than the + import failing. + * sync, assist, push, pull: Skip more types of remotes when they + are not available due to eg being on a drive that is offline. + (directory, borg, bup, ddar, gcrypt, rsync) + * info: Added available to the info displayed for a remote. + * Added AVAILABILITY UNAVAILABLE and the UNAVAILABLERESPONSE extension + to the external special remote protocol. + * The remote.name.annex-availability git config is no longer used. + * Avoid using curl when annex.security.allowed-ip-addresses is set + but neither annex.web-options nor annex.security.allowed-url-schemes + is set to a value that needs curl. + * Stop bundling curl in the OSX dmg and linux standalone image. + * diffdriver: Added --get option. + * diffdriver: Refuse to run when not in a git-annex repository. + + -- Joey Hess Mon, 28 Aug 2023 12:40:37 -0400 + git-annex (10.20230802) upstream; urgency=medium * satisfy: New command that gets/sends/drops content to satisfy diff --git a/CmdLine/GitAnnex.hs b/CmdLine/GitAnnex.hs --- a/CmdLine/GitAnnex.hs +++ b/CmdLine/GitAnnex.hs @@ -115,6 +115,7 @@ import qualified Command.Indirect import qualified Command.Upgrade import qualified Command.Forget +import qualified Command.OldKeys import qualified Command.P2P import qualified Command.Proxy import qualified Command.DiffDriver @@ -236,6 +237,7 @@ , Command.Indirect.cmd , Command.Upgrade.cmd , Command.Forget.cmd + , Command.OldKeys.cmd , Command.P2P.cmd , Command.Proxy.cmd , Command.DiffDriver.cmd diff --git a/Command/AddUrl.hs b/Command/AddUrl.hs --- a/Command/AddUrl.hs +++ b/Command/AddUrl.hs @@ -33,7 +33,7 @@ import Utility.Metered import Utility.HtmlDetect import Utility.Path.Max -import Utility.Url (parseURIPortable) +import Utility.Url.Parse import qualified Utility.RawFilePath as R import qualified Annex.Transfer as Transfer diff --git a/Command/DiffDriver.hs b/Command/DiffDriver.hs --- a/Command/DiffDriver.hs +++ b/Command/DiffDriver.hs @@ -11,15 +11,16 @@ import Annex.Content import Annex.Link import Git.Types +import qualified Command.Get cmd :: Command -cmd = dontCheck repoExists $ - command "diffdriver" SectionPlumbing - "git diff driver" - ("-- cmd --") (seek <$$> optParser) +cmd = command "diffdriver" SectionPlumbing + "git diff driver" + ("-- cmd --") (seek <$$> optParser) data Options = Options { textDiff :: Bool + , getOption :: Bool , restOptions :: CmdParams } @@ -29,16 +30,16 @@ ( long "text" <> help "diff text files with diff(1)" ) + <*> switch + ( long "get" + <> help "get file contents from remotes" + ) <*> cmdParams desc seek :: Options -> CommandSeek -seek = commandAction . start - -start :: Options -> CommandStart -start opts = do +seek opts = do let (req, differ) = parseReq opts - void $ liftIO . exitBool =<< liftIO . differ =<< fixupReq req - stop + void $ liftIO . exitBool =<< liftIO . differ =<< fixupReq req opts data Req = Req @@ -99,22 +100,35 @@ - - In either case, adjust the Req to instead point to the actual - location of the annexed object (which may or may not be present). + - + - This also gets objects from remotes when the getOption is set. -} -fixupReq :: Req -> Annex Req -fixupReq req@(UnmergedReq {}) = return req -fixupReq req@(Req {}) = +fixupReq :: Req -> Options -> Annex Req +fixupReq req@(UnmergedReq {}) _ = return req +fixupReq req@(Req {}) opts = check rOldFile rOldMode (\r f -> r { rOldFile = f }) req >>= check rNewFile rNewMode (\r f -> r { rNewFile = f }) where check getfile getmode setfile r = case readTreeItemType (encodeBS (getmode r)) of Just TreeSymlink -> do v <- getAnnexLinkTarget' f False - maybe (return r) repoint (parseLinkTargetOrPointer =<< v) - _ -> maybe (return r) repoint =<< liftIO (isPointerFile f) + maybe (return r) go (parseLinkTargetOrPointer =<< v) + _ -> maybe (return r) go =<< liftIO (isPointerFile f) where + f = toRawFilePath (getfile r) + go k = do + when (getOption opts) $ + unlessM (inAnnex k) $ + commandAction $ + starting "get" ai si $ + Command.Get.perform k af + repoint k + where + ai = OnlyActionOn k (ActionItemKey k) + si = SeekInput [] + af = AssociatedFile (Just f) repoint k = withObjectLoc k $ pure . setfile r . fromRawFilePath - f = toRawFilePath (getfile r) externalDiffer :: String -> [String] -> Differ externalDiffer c ps = \req -> boolSystem c (map Param ps ++ serializeReq req ) diff --git a/Command/FromKey.hs b/Command/FromKey.hs --- a/Command/FromKey.hs +++ b/Command/FromKey.hs @@ -20,7 +20,7 @@ import Annex.FileMatcher import Annex.Ingest import Git.FilePath -import Utility.Url +import Utility.Url.Parse import Network.URI diff --git a/Command/Info.hs b/Command/Info.hs --- a/Command/Info.hs +++ b/Command/Info.hs @@ -1,6 +1,6 @@ {- git-annex command - - - Copyright 2011-2022 Joey Hess + - Copyright 2011-2023 Joey Hess - - Licensed under the GNU AGPL version 3 or higher. -} @@ -43,6 +43,7 @@ import Types.Key import Types.TrustLevel import Types.FileMatcher +import Types.Availability import qualified Limit import Messages.JSON (DualDisp(..), ObjectMap(..)) import Annex.BloomFilter @@ -109,6 +110,7 @@ , bytesOption :: Bool , batchOption :: BatchMode , autoenableOption :: Bool + , deadrepositoriesOption :: Bool } optParser :: CmdParamsDesc -> Parser InfoOptions @@ -123,6 +125,10 @@ ( long "autoenable" <> help "list special remotes that are configured to autoenable" ) + <*> switch + ( long "dead-repositories" + <> help "list repositories that have been marked as dead" + ) seek :: InfoOptions -> CommandSeek seek o = case batchOption o of @@ -134,7 +140,9 @@ start o [] = do if autoenableOption o then autoenableInfo - else globalInfo o + else if deadrepositoriesOption o + then deadrepositoriesInfo o + else globalInfo o stop start o ps = do mapM_ (\p -> itemInfo o (SeekInput [p], p)) ps @@ -163,6 +171,11 @@ showRaw (encodeBS s) return True +deadrepositoriesInfo :: InfoOptions -> Annex () +deadrepositoriesInfo o = showCustom "info" (SeekInput []) $ do + evalStateT (showStat (repo_list DeadTrusted)) (emptyStatInfo o) + return True + itemInfo :: InfoOptions -> (SeekInput, String) -> Annex () itemInfo o (si, p) = ifM (isdir (toRawFilePath p)) ( dirInfo o p si @@ -300,6 +313,7 @@ [ remote_name , remote_cost , remote_type + , remote_availabile ] uuid_fast_stats :: UUID -> [Stat] @@ -384,6 +398,11 @@ remote_type :: Remote -> Stat remote_type r = simpleStat "type" $ pure $ Remote.typename $ Remote.remotetype r + +remote_availabile :: Remote -> Stat +remote_availabile r = simpleStat "available" $ lift $ + either show (\av -> boolConfig (av /= Unavailable)) + <$> tryNonAsync (Remote.availability r) local_annex_keys :: Stat local_annex_keys = stat "local annex keys" $ json show $ diff --git a/Command/OldKeys.hs b/Command/OldKeys.hs new file mode 100644 --- /dev/null +++ b/Command/OldKeys.hs @@ -0,0 +1,104 @@ +{- git-annex command + - + - Copyright 2023 Joey Hess + - + - Licensed under the GNU AGPL version 3 or higher. + -} + +module Command.OldKeys where + +import Command +import Git.Types +import Git.Sha +import qualified Git.Command +import qualified Git.DiffTree as DiffTree +import qualified Annex +import Annex.CatFile +import Utility.Terminal +import qualified Utility.Format +import qualified Database.Keys + +import qualified Data.ByteString.Char8 as S8 + +cmd :: Command +cmd = noCommit $ + command "oldkeys" SectionQuery + "list keys used for old versions of files" + paramPaths (seek <$$> optParser) + +data OldKeysOptions = OldKeysOptions + { fileOptions :: CmdParams + , revisionRange :: Maybe String + , uncheckedOption :: Bool + } + +optParser :: CmdParamsDesc -> Parser OldKeysOptions +optParser desc = OldKeysOptions + <$> cmdParams desc + <*> optional (strOption + ( long "revision-range" <> metavar "RANGE" + <> help "limit to a revision range" + )) + <*> switch + ( long "unchecked" + <> help "don't check if current files use keys" + ) + +seek :: OldKeysOptions -> CommandSeek +seek o = do + isterminal <- liftIO $ checkIsTerminal stdout + withdiff $ \l -> + forM_ l $ \i -> + when (DiffTree.srcsha i `notElem` nullShas) $ do + catKey (DiffTree.srcsha i) >>= \case + Just key -> commandAction $ + start o isterminal key + Nothing -> return () + where + withdiff a = do + (output, cleanup) <- Annex.inRepo $ + Git.Command.pipeNullSplit ps + let l = filter (isfilemode . DiffTree.srcmode) + (DiffTree.parseDiffRaw output) + r <- a l + liftIO $ void cleanup + return r + + ps = + [ Param "log" + , Param "-z" + -- Don't convert pointer files. + , Param "--no-textconv" + -- Don't abbreviate hashes. + , Param "--no-abbrev" + -- Don't show renames. + , Param "--no-renames" + -- Output the raw diff. + , Param "--raw" + -- Avoid outputting anything except for the raw diff. + , Param "--pretty=" + ] + ++ case revisionRange o of + Nothing -> [] + Just rr -> [Param rr] + ++ map File (fileOptions o) + + isfilemode m = case toTreeItemType m of + Just TreeFile -> True + Just TreeExecutable -> True + Just TreeSymlink -> True + _ -> False + +start :: OldKeysOptions -> IsTerminal -> Key -> CommandStart +start o (IsTerminal isterminal) key + | uncheckedOption o = go + | otherwise = Database.Keys.getAssociatedFiles key >>= \case + [] -> go + _ -> stop + where + go = startingCustomOutput key $ do + liftIO $ S8.putStrLn $ if isterminal + then Utility.Format.encode_c (const False) sk + else sk + next $ return True + sk = serializeKey' key diff --git a/Command/Sync.hs b/Command/Sync.hs --- a/Command/Sync.hs +++ b/Command/Sync.hs @@ -78,6 +78,7 @@ import Annex.CheckIgnore import Types.FileMatcher import Types.GitConfig +import Types.Availability import qualified Database.Export as Export import Utility.Bloom import Utility.OptParse @@ -256,8 +257,6 @@ seek :: SyncOptions -> CommandSeek seek o = do - warnSyncContentTransition o - prepMerge seek' o @@ -267,6 +266,7 @@ let withbranch a = a =<< getCurrentBranch remotes <- syncRemotes (syncWith o) + warnSyncContentTransition o remotes -- Remotes that are git repositories, not (necesarily) special remotes. let gitremotes = filter (Remote.gitSyncableRemoteType . Remote.remotetype) remotes -- Remotes that contain annex object content. @@ -371,10 +371,10 @@ remoteBranch :: Remote -> Git.Ref -> Git.Ref remoteBranch remote = Git.Ref.underBase $ "refs/remotes/" ++ Remote.name remote --- Do automatic initialization of remotes when possible when getting remote --- list. syncRemotes :: [String] -> Annex [Remote] syncRemotes ps = do + -- Do automatic initialization of remotes when possible + -- when getting remote list. remotelist <- Remote.remoteList' True available <- filterM (liftIO . getDynamicConfig . remoteAnnexSync . Remote.gitconfig) remotelist syncRemotes' ps available @@ -389,10 +389,9 @@ listed = concat <$> mapM Remote.byNameOrGroup ps - good r - | Remote.gitSyncableRemoteType (Remote.remotetype r) = - Remote.Git.repoAvail =<< Remote.getRepo r - | otherwise = return True + good r = tryNonAsync (Remote.availability r) >>= return . \case + Right Unavailable -> False + _ -> True fastest = fromMaybe [] . headMaybe . Remote.byCost @@ -1102,23 +1101,28 @@ HasGitConfig (Just c) -> return c _ -> return d --- Transition started May 2023, should wait until that has been in a Debian --- stable release before completing the transition. -warnSyncContentTransition :: SyncOptions -> Annex () -warnSyncContentTransition o +-- See doc/todo/finish_sync_content_transition.mdwn +warnSyncContentTransition :: SyncOptions -> [Remote] -> Annex () +warnSyncContentTransition o remotes | operationMode o /= SyncMode = noop | isJust (noContentOption o) || isJust (contentOption o) = noop | not (null (contentOfOption o)) = noop | otherwise = getGitConfigVal' annexSyncContent >>= \case HasGlobalConfig (Just _) -> noop HasGitConfig (Just _) -> noop - _ -> showwarning + _ -> do + m <- preferredContentMap + hereu <- getUUID + when (any (`M.member` m) (hereu:map Remote.uuid remotes)) $ + showwarning where showwarning = earlyWarning $ - "git-annex sync will change default behavior to operate on" - <> " --content in a future version of git-annex. Recommend" - <> " you explicitly use --no-content (or -g) to prepare for" - <> " that change. (Or you can configure annex.synccontent)" + "git-annex sync will change default behavior in the future to" + <> " send content to repositories that have" + <> " preferred content configured. If you do not want this to" + <> " send any content, use --no-content (or -g)" + <> " to prepare for that change." + <> " (Or you can configure annex.synccontent)" notOnlyAnnex :: SyncOptions -> Annex Bool notOnlyAnnex o = not <$> onlyAnnex o diff --git a/Command/Uninit.hs b/Command/Uninit.hs --- a/Command/Uninit.hs +++ b/Command/Uninit.hs @@ -141,7 +141,7 @@ prepareRemoveAnnexDir' :: FilePath -> IO () prepareRemoveAnnexDir' annexdir = - dirTreeRecursiveSkipping (const False) annexdir + emptyWhenDoesNotExist (dirTreeRecursiveSkipping (const False) annexdir) >>= mapM_ (void . tryIO . allowWrite . toRawFilePath) {- Keys that were moved out of the annex have a hard link still in the diff --git a/Git/Construct.hs b/Git/Construct.hs --- a/Git/Construct.hs +++ b/Git/Construct.hs @@ -39,7 +39,7 @@ import Git.FilePath import qualified Git.Url as Url import Utility.UserInfo -import Utility.Url (parseURIPortable) +import Utility.Url.Parse import qualified Data.ByteString as B import qualified System.FilePath.ByteString as P diff --git a/Git/Credential.hs b/Git/Credential.hs --- a/Git/Credential.hs +++ b/Git/Credential.hs @@ -15,6 +15,7 @@ import Git.Command import qualified Git.Config as Config import Utility.Url +import Utility.Url.Parse import qualified Data.Map as M import Network.URI diff --git a/Git/Objects.hs b/Git/Objects.hs --- a/Git/Objects.hs +++ b/Git/Objects.hs @@ -32,7 +32,7 @@ listLooseObjectShas :: Repo -> IO [Sha] listLooseObjectShas r = catchDefaultIO [] $ mapMaybe (extractSha . encodeBS . concat . reverse . take 2 . reverse . splitDirectories) - <$> dirContentsRecursiveSkipping (== "pack") True (fromRawFilePath (objectsDir r)) + <$> emptyWhenDoesNotExist (dirContentsRecursiveSkipping (== "pack") True (fromRawFilePath (objectsDir r))) looseObjectFile :: Repo -> Sha -> RawFilePath looseObjectFile r sha = objectsDir r P. prefix P. rest diff --git a/Git/Repair.hs b/Git/Repair.hs --- a/Git/Repair.hs +++ b/Git/Repair.hs @@ -88,7 +88,7 @@ void $ tryIO $ pipeWrite [Param "unpack-objects", Param "-r"] r' $ \h -> L.hPut h =<< L.readFile packfile - objs <- dirContentsRecursive tmpdir + objs <- emptyWhenDoesNotExist (dirContentsRecursive tmpdir) forM_ objs $ \objfile -> do f <- relPathDirToFile (toRawFilePath tmpdir) @@ -255,7 +255,7 @@ let topsegs = length (splitPath refdir) - 1 let toref = Ref . toInternalGitPath . encodeBS . joinPath . drop topsegs . splitPath - map toref <$> dirContentsRecursive refdir + map toref <$> emptyWhenDoesNotExist (dirContentsRecursive refdir) explodePackedRefsFile :: Repo -> IO () explodePackedRefsFile r = do diff --git a/Limit.hs b/Limit.hs --- a/Limit.hs +++ b/Limit.hs @@ -509,8 +509,9 @@ present <- S.fromList <$> Remote.keyLocations key return $ S.null $ want `S.difference` present -{- Skip files that are only present in repositories that are not in the - - group. -} +{- Skip files unless they are present in at least one repository that is in + - the specified group, and are not present in any repositories that are not + - in the specified group. -} addOnlyInGroup :: String -> Annex () addOnlyInGroup groupname = addLimit $ limitOnlyInGroup groupMap groupname @@ -532,7 +533,8 @@ check notpresent want key = do locs <- S.fromList <$> Remote.keyLocations key let present = locs `S.difference` notpresent - return $ not $ S.null $ present `S.intersection` want + return $ not (S.null $ present `S.intersection` want) + && S.null (S.filter (`S.notMember` want) present) {- Adds a limit to skip files not using a specified key-value backend. -} addInBackend :: String -> Annex () diff --git a/Logs/Transfer.hs b/Logs/Transfer.hs --- a/Logs/Transfer.hs +++ b/Logs/Transfer.hs @@ -152,7 +152,7 @@ infos <- mapM checkTransfer transfers return $ mapMaybe running $ zip transfers infos where - findfiles = liftIO . mapM (dirContentsRecursive . fromRawFilePath) + findfiles = liftIO . mapM (emptyWhenDoesNotExist . dirContentsRecursive . fromRawFilePath) =<< mapM (fromRepo . transferDir) dirs running (t, Just i) = Just (t, i) running (_, Nothing) = Nothing @@ -179,7 +179,7 @@ return $ case (mt, mi) of (Just t, Just i) -> Just (t, i) _ -> Nothing - findfiles = liftIO . mapM (dirContentsRecursive . fromRawFilePath) + findfiles = liftIO . mapM (emptyWhenDoesNotExist . dirContentsRecursive . fromRawFilePath) =<< mapM (fromRepo . failedTransferDir u) [Download, Upload] clearFailedTransfers :: UUID -> Annex [(Transfer, TransferInfo)] diff --git a/Remote.hs b/Remote.hs --- a/Remote.hs +++ b/Remote.hs @@ -411,9 +411,12 @@ costmap = M.fromListWith (++) . map costpair costpair r = (cost r, [r]) -checkAvailable :: Bool -> Remote -> IO Bool -checkAvailable assumenetworkavailable = - maybe (return assumenetworkavailable) doesDirectoryExist . localpath +checkAvailable :: Bool -> Remote -> Annex Bool +checkAvailable assumenetworkavailable r = tryNonAsync (availability r) >>= \case + Left _e -> return assumenetworkavailable + Right LocallyAvailable -> return True + Right GloballyAvailable -> return assumenetworkavailable + Right Unavailable -> return False hasKey :: Remote -> Key -> Annex (Either String Bool) hasKey r k = either (Left . show) Right <$> tryNonAsync (checkPresent r k) diff --git a/Remote/Adb.hs b/Remote/Adb.hs --- a/Remote/Adb.hs +++ b/Remote/Adb.hs @@ -113,7 +113,7 @@ , gitconfig = gc , localpath = Nothing , remotetype = remote - , availability = LocallyAvailable + , availability = pure LocallyAvailable , readonly = False , appendonly = False , untrustworthy = False diff --git a/Remote/BitTorrent.hs b/Remote/BitTorrent.hs --- a/Remote/BitTorrent.hs +++ b/Remote/BitTorrent.hs @@ -23,7 +23,7 @@ import Messages.Progress import Utility.Metered import Utility.Tmp -import Utility.Url (parseURIPortable) +import Utility.Url.Parse import Backend.URL import Annex.Perms import Annex.Tmp @@ -88,7 +88,7 @@ , readonly = True , appendonly = False , untrustworthy = False - , availability = GloballyAvailable + , availability = pure GloballyAvailable , remotetype = remote , mkUnavailable = return Nothing , getInfo = return [] diff --git a/Remote/Borg.hs b/Remote/Borg.hs --- a/Remote/Borg.hs +++ b/Remote/Borg.hs @@ -1,6 +1,6 @@ {- Using borg as a remote. - - - Copyright 2020,2021 Joey Hess + - Copyright 2020,2023 Joey Hess - - Licensed under the GNU AGPL version 3 or higher. -} @@ -23,6 +23,7 @@ import Annex.SpecialRemote.Config import Remote.Helper.Special import Remote.Helper.ExportImport +import Remote.Helper.Path import Annex.UUID import Types.ProposedAccepted import Utility.Metered @@ -112,7 +113,7 @@ , gitconfig = gc , localpath = borgRepoLocalPath borgrepo , remotetype = remote - , availability = if borgLocal borgrepo then LocallyAvailable else GloballyAvailable + , availability = checkAvailability borgrepo , readonly = False , appendonly = False -- When the user sets the appendonly field, they are @@ -160,8 +161,12 @@ borgRepoLocalPath :: BorgRepo -> Maybe FilePath borgRepoLocalPath r@(BorgRepo p) - | borgLocal r && not (null p) = Just p + | borgLocal r = Just p | otherwise = Nothing + +checkAvailability :: BorgRepo -> Annex Availability +checkAvailability borgrepo@(BorgRepo r) = + checkPathAvailability (borgLocal borgrepo) r listImportableContentsM :: UUID -> BorgRepo -> ParsedRemoteConfig -> Annex (Maybe (ImportableContentsChunkable Annex (ContentIdentifier, ByteSize))) listImportableContentsM u borgrepo c = prompt $ do diff --git a/Remote/Bup.hs b/Remote/Bup.hs --- a/Remote/Bup.hs +++ b/Remote/Bup.hs @@ -32,6 +32,7 @@ import Annex.SpecialRemote.Config import Remote.Helper.Special import Remote.Helper.ExportImport +import Remote.Helper.Path import Utility.Hash import Utility.UserInfo import Annex.UUID @@ -97,7 +98,9 @@ then Just buprepo else Nothing , remotetype = remote - , availability = if bupLocal buprepo then LocallyAvailable else GloballyAvailable + , availability = if null buprepo + then pure LocallyAvailable + else checkPathAvailability (bupLocal buprepo) buprepo , readonly = False , appendonly = False , untrustworthy = False diff --git a/Remote/Ddar.hs b/Remote/Ddar.hs --- a/Remote/Ddar.hs +++ b/Remote/Ddar.hs @@ -25,6 +25,7 @@ import Annex.SpecialRemote.Config import Remote.Helper.Special import Remote.Helper.ExportImport +import Remote.Helper.Path import Annex.Ssh import Annex.UUID import Utility.SshHost @@ -98,7 +99,9 @@ then Just $ ddarRepoLocation ddarrepo else Nothing , remotetype = remote - , availability = if ddarLocal ddarrepo then LocallyAvailable else GloballyAvailable + , availability = checkPathAvailability + (ddarLocal ddarrepo && not (null $ ddarRepoLocation ddarrepo)) + (ddarRepoLocation ddarrepo) , readonly = False , appendonly = False , untrustworthy = False diff --git a/Remote/Directory.hs b/Remote/Directory.hs --- a/Remote/Directory.hs +++ b/Remote/Directory.hs @@ -34,6 +34,7 @@ import Annex.SpecialRemote.Config import Remote.Helper.Special import Remote.Helper.ExportImport +import Remote.Helper.Path import Types.Import import qualified Remote.Directory.LegacyChunked as Legacy import Annex.CopyFile @@ -134,7 +135,7 @@ , readonly = False , appendonly = False , untrustworthy = False - , availability = LocallyAvailable + , availability = checkPathAvailability True dir' , remotetype = remote , mkUnavailable = gen r u rc (gc { remoteAnnexDirectory = Just "/dev/null" }) rs diff --git a/Remote/External.hs b/Remote/External.hs --- a/Remote/External.hs +++ b/Remote/External.hs @@ -68,7 +68,7 @@ | externaltype == "readonly" = do c <- parsedRemoteConfig remote rc cst <- remoteCost gc c expensiveRemoteCost - let rmt = mk c cst GloballyAvailable + let rmt = mk c cst (pure GloballyAvailable) Nothing (externalInfo externaltype) Nothing @@ -87,7 +87,6 @@ (Git.remoteName r) (Just rs) Annex.addCleanupAction (RemoteCleanup u) $ stopExternal external cst <- getCost external r gc c - avail <- getAvailability external r gc exportsupported <- if exportTree c then checkExportSupported' external else return False @@ -107,7 +106,7 @@ let cheapexportsupported = if exportsupported then exportIsSupported else exportUnsupported - let rmt = mk c cst avail + let rmt = mk c cst (getAvailability external) (Just (whereisKeyM external)) (getInfoM external) (Just (claimUrlM external)) @@ -777,25 +776,16 @@ return c defcst = expensiveRemoteCost -{- Caches the availability in the git config to avoid needing to start up an - - external special remote every time time just to ask it what its - - availability is. - - - - Most remotes do not bother to implement a reply to this request; +{- Most remotes do not bother to implement a reply to this request; - globally available is the default. -} -getAvailability :: External -> Git.Repo -> RemoteGitConfig -> Annex Availability -getAvailability external r gc = - maybe (catchNonAsync query (const (pure defavail))) return - (remoteAnnexAvailability gc) +getAvailability :: External -> Annex Availability +getAvailability external = catchNonAsync query (const (pure defavail)) where - query = do - avail <- handleRequest external GETAVAILABILITY Nothing $ \req -> case req of - AVAILABILITY avail -> result avail - UNSUPPORTED_REQUEST -> result defavail - _ -> Nothing - setRemoteAvailability r avail - return avail + query = handleRequest external GETAVAILABILITY Nothing $ \req -> case req of + AVAILABILITY avail -> result avail + UNSUPPORTED_REQUEST -> result defavail + _ -> Nothing defavail = GloballyAvailable claimUrlM :: External -> URLString -> Annex Bool diff --git a/Remote/External/Types.hs b/Remote/External/Types.hs --- a/Remote/External/Types.hs +++ b/Remote/External/Types.hs @@ -53,7 +53,8 @@ import Types.Availability (Availability(..)) import Types.Key import Git.Types -import Utility.Url (URLString, parseURIPortable) +import Utility.Url (URLString) +import Utility.Url.Parse import qualified Utility.SimpleProtocol as Proto import Control.Concurrent.STM @@ -109,6 +110,7 @@ supportedExtensionList = ExtensionList [ "INFO" , "GETGITREMOTENAME" + , "UNAVAILABLERESPONSE" , asyncExtension ] @@ -446,9 +448,11 @@ instance Proto.Serializable Availability where serialize GloballyAvailable = "GLOBAL" serialize LocallyAvailable = "LOCAL" + serialize Unavailable = "UNAVAILABLE" deserialize "GLOBAL" = Just GloballyAvailable deserialize "LOCAL" = Just LocallyAvailable + deserialize "UNAVAILABLE" = Just Unavailable deserialize _ = Nothing instance Proto.Serializable [(URLString, Size, FilePath)] where diff --git a/Remote/GCrypt.hs b/Remote/GCrypt.hs --- a/Remote/GCrypt.hs +++ b/Remote/GCrypt.hs @@ -158,7 +158,7 @@ , readonly = Git.repoIsHttp r , appendonly = False , untrustworthy = False - , availability = availabilityCalc r + , availability = repoAvail r , remotetype = remote , mkUnavailable = return Nothing , getInfo = gitRepoInfo this diff --git a/Remote/Git.hs b/Remote/Git.hs --- a/Remote/Git.hs +++ b/Remote/Git.hs @@ -1,6 +1,6 @@ {- Standard git remotes. - - - Copyright 2011-2021 Joey Hess + - Copyright 2011-2023 Joey Hess - - Licensed under the GNU AGPL version 3 or higher. -} @@ -11,7 +11,6 @@ module Remote.Git ( remote, configRead, - repoAvail, onLocalRepo, ) where @@ -210,7 +209,7 @@ , readonly = Git.repoIsHttp r , appendonly = False , untrustworthy = False - , availability = availabilityCalc r + , availability = repoAvail r , remotetype = remote , mkUnavailable = unavailable r u rc gc rs , getInfo = gitRepoInfo new @@ -231,22 +230,6 @@ in r { Git.location = Git.Url (url { uriAuthority = Just auth' })} Nothing -> r { Git.location = Git.Unknown } _ -> r -- already unavailable - -{- Checks relatively inexpensively if a repository is available for use. -} -repoAvail :: Git.Repo -> Annex Bool -repoAvail r - | Git.repoIsHttp r = return True - | Git.GCrypt.isEncrypted r = do - g <- gitRepo - liftIO $ do - er <- Git.GCrypt.encryptedRemote g r - if Git.repoIsLocal er || Git.repoIsLocalUnknown er - then catchBoolIO $ - void (Git.Config.read er) >> return True - else return True - | Git.repoIsUrl r = return True - | Git.repoIsLocalUnknown r = return False - | otherwise = liftIO $ isJust <$> catchMaybeIO (Git.Config.read r) {- Tries to read the config for a specified remote, updates state, and - returns the updated repo. -} diff --git a/Remote/GitLFS.hs b/Remote/GitLFS.hs --- a/Remote/GitLFS.hs +++ b/Remote/GitLFS.hs @@ -130,7 +130,7 @@ , gitconfig = gc , localpath = Nothing , remotetype = remote - , availability = GloballyAvailable + , availability = pure GloballyAvailable , readonly = False -- content cannot be removed from a git-lfs repo , appendonly = True diff --git a/Remote/Glacier.hs b/Remote/Glacier.hs --- a/Remote/Glacier.hs +++ b/Remote/Glacier.hs @@ -103,7 +103,7 @@ , readonly = False , appendonly = False , untrustworthy = False - , availability = GloballyAvailable + , availability = pure GloballyAvailable , remotetype = remote , mkUnavailable = return Nothing , getInfo = includeCredsInfo c (AWS.creds u) $ diff --git a/Remote/Helper/Git.hs b/Remote/Helper/Git.hs --- a/Remote/Helper/Git.hs +++ b/Remote/Helper/Git.hs @@ -9,9 +9,11 @@ import Annex.Common import qualified Git +import qualified Git.GCrypt import Types.Availability import qualified Types.Remote as Remote import qualified Utility.RawFilePath as R +import qualified Git.Config import Data.Time.Clock.POSIX import System.PosixCompat.Files (modificationTime) @@ -21,13 +23,28 @@ localpathCalc :: Git.Repo -> Maybe FilePath localpathCalc r - | availabilityCalc r == GloballyAvailable = Nothing + | not (Git.repoIsLocal r) && not (Git.repoIsLocalUnknown r) = Nothing | otherwise = Just $ fromRawFilePath $ Git.repoPath r -availabilityCalc :: Git.Repo -> Availability -availabilityCalc r - | (Git.repoIsLocal r || Git.repoIsLocalUnknown r) = LocallyAvailable - | otherwise = GloballyAvailable +{- Checks relatively inexpensively if a repository is available for use. -} +repoAvail :: Git.Repo -> Annex Availability +repoAvail r + | Git.repoIsHttp r = return GloballyAvailable + | Git.GCrypt.isEncrypted r = do + g <- gitRepo + liftIO $ do + er <- Git.GCrypt.encryptedRemote g r + if Git.repoIsLocal er || Git.repoIsLocalUnknown er + then checklocal er + else return GloballyAvailable + | Git.repoIsUrl r = return GloballyAvailable + | Git.repoIsLocalUnknown r = return Unavailable + | otherwise = checklocal r + where + checklocal r' = ifM (liftIO $ isJust <$> catchMaybeIO (Git.Config.read r')) + ( return LocallyAvailable + , return Unavailable + ) {- Avoids performing an action on a local repository that's not usable. - Does not check that the repository is still available on disk. -} @@ -40,7 +57,7 @@ gitRepoInfo r = do d <- fromRawFilePath <$> fromRepo Git.localGitDir mtimes <- liftIO $ mapM (\p -> modificationTime <$> R.getFileStatus (toRawFilePath p)) - =<< dirContentsRecursive (d "refs" "remotes" Remote.name r) + =<< emptyWhenDoesNotExist (dirContentsRecursive (d "refs" "remotes" Remote.name r)) let lastsynctime = case mtimes of [] -> "never" _ -> show $ posixSecondsToUTCTime $ realToFrac $ maximum mtimes diff --git a/Remote/Helper/Path.hs b/Remote/Helper/Path.hs new file mode 100644 --- /dev/null +++ b/Remote/Helper/Path.hs @@ -0,0 +1,19 @@ +{- Utilities for remotes located in a path in the filesystem. + - + - Copyright 2023 Joey Hess + - + - Licensed under the GNU AGPL version 3 or higher. + -} + +module Remote.Helper.Path where + +import Annex.Common +import Types.Availability + +checkPathAvailability :: Bool -> FilePath -> Annex Availability +checkPathAvailability islocal d + | not islocal = return GloballyAvailable + | otherwise = ifM (liftIO $ doesDirectoryExist d) + ( return LocallyAvailable + , return Unavailable + ) diff --git a/Remote/Hook.hs b/Remote/Hook.hs --- a/Remote/Hook.hs +++ b/Remote/Hook.hs @@ -82,7 +82,7 @@ , readonly = False , appendonly = False , untrustworthy = False - , availability = GloballyAvailable + , availability = pure GloballyAvailable , remotetype = remote , mkUnavailable = gen r u rc (gc { remoteAnnexHookType = Just "!dne!" }) diff --git a/Remote/HttpAlso.hs b/Remote/HttpAlso.hs --- a/Remote/HttpAlso.hs +++ b/Remote/HttpAlso.hs @@ -95,7 +95,7 @@ , readonly = True , appendonly = False , untrustworthy = False - , availability = GloballyAvailable + , availability = pure GloballyAvailable , remotetype = remote , mkUnavailable = return Nothing , getInfo = return [] diff --git a/Remote/P2P.hs b/Remote/P2P.hs --- a/Remote/P2P.hs +++ b/Remote/P2P.hs @@ -77,7 +77,7 @@ , readonly = False , appendonly = False , untrustworthy = False - , availability = GloballyAvailable + , availability = pure GloballyAvailable , remotetype = remote , mkUnavailable = return Nothing , getInfo = gitRepoInfo this diff --git a/Remote/Rsync.hs b/Remote/Rsync.hs --- a/Remote/Rsync.hs +++ b/Remote/Rsync.hs @@ -31,6 +31,7 @@ import Annex.Perms import Remote.Helper.Special import Remote.Helper.ExportImport +import Remote.Helper.Path import Types.Export import Types.ProposedAccepted import Remote.Rsync.RsyncUrl @@ -120,7 +121,7 @@ , readonly = False , appendonly = False , untrustworthy = False - , availability = if islocal then LocallyAvailable else GloballyAvailable + , availability = checkPathAvailability islocal (rsyncUrl o) , remotetype = remote , mkUnavailable = return Nothing , getInfo = return [("url", url)] diff --git a/Remote/S3.hs b/Remote/S3.hs --- a/Remote/S3.hs +++ b/Remote/S3.hs @@ -249,7 +249,7 @@ , readonly = False , appendonly = False , untrustworthy = False - , availability = GloballyAvailable + , availability = pure GloballyAvailable , remotetype = remote , mkUnavailable = gen r u (M.insert hostField (Proposed "!dne!") rc) gc rs , getInfo = includeCredsInfo c (AWS.creds u) (s3Info c info) diff --git a/Remote/Tahoe.hs b/Remote/Tahoe.hs --- a/Remote/Tahoe.hs +++ b/Remote/Tahoe.hs @@ -108,7 +108,7 @@ , readonly = False , appendonly = False , untrustworthy = False - , availability = GloballyAvailable + , availability = pure GloballyAvailable , remotetype = remote , mkUnavailable = return Nothing , getInfo = return [] diff --git a/Remote/Web.hs b/Remote/Web.hs --- a/Remote/Web.hs +++ b/Remote/Web.hs @@ -93,7 +93,7 @@ , readonly = True , appendonly = False , untrustworthy = False - , availability = GloballyAvailable + , availability = pure GloballyAvailable , remotetype = remote , mkUnavailable = return Nothing , getInfo = return [] diff --git a/Remote/WebDAV.hs b/Remote/WebDAV.hs --- a/Remote/WebDAV.hs +++ b/Remote/WebDAV.hs @@ -117,7 +117,7 @@ , readonly = False , appendonly = False , untrustworthy = False - , availability = GloballyAvailable + , availability = pure GloballyAvailable , remotetype = remote , mkUnavailable = gen r u (M.insert urlField (Proposed "http://!dne!/") rc) gc rs , getInfo = includeCredsInfo c (davCreds u) $ diff --git a/RemoteDaemon/Types.hs b/RemoteDaemon/Types.hs --- a/RemoteDaemon/Types.hs +++ b/RemoteDaemon/Types.hs @@ -15,7 +15,7 @@ import qualified Utility.SimpleProtocol as Proto import Types.GitConfig import Annex.ChangedRefs (ChangedRefs) -import Utility.Url +import Utility.Url.Parse import Network.URI import Control.Concurrent diff --git a/Types/Availability.hs b/Types/Availability.hs --- a/Types/Availability.hs +++ b/Types/Availability.hs @@ -7,5 +7,5 @@ module Types.Availability where -data Availability = GloballyAvailable | LocallyAvailable - deriving (Eq, Show, Read) +data Availability = GloballyAvailable | LocallyAvailable | Unavailable + deriving (Eq, Show) diff --git a/Types/GitConfig.hs b/Types/GitConfig.hs --- a/Types/GitConfig.hs +++ b/Types/GitConfig.hs @@ -37,7 +37,6 @@ import Config.Cost import Types.UUID import Types.Distribution -import Types.Availability import Types.Concurrency import Types.NumCopies import Types.Difference @@ -351,7 +350,6 @@ , remoteAnnexTrustLevel :: Maybe String , remoteAnnexStartCommand :: Maybe String , remoteAnnexStopCommand :: Maybe String - , remoteAnnexAvailability :: Maybe Availability , remoteAnnexSpeculatePresent :: Bool , remoteAnnexBare :: Maybe Bool , remoteAnnexRetry :: Maybe Integer @@ -416,7 +414,6 @@ , remoteAnnexTrustLevel = notempty $ getmaybe "trustlevel" , remoteAnnexStartCommand = notempty $ getmaybe "start-command" , remoteAnnexStopCommand = notempty $ getmaybe "stop-command" - , remoteAnnexAvailability = getmayberead "availability" , remoteAnnexSpeculatePresent = getbool "speculate-present" False , remoteAnnexBare = getmaybebool "bare" , remoteAnnexRetry = getmayberead "retry" diff --git a/Types/Remote.hs b/Types/Remote.hs --- a/Types/Remote.hs +++ b/Types/Remote.hs @@ -152,7 +152,8 @@ -- decide. , untrustworthy :: Bool -- a Remote can be globally available. (Ie, "in the cloud".) - , availability :: Availability + -- Some Remotes can mark themselves unavailable. + , availability :: a Availability -- the type of the remote , remotetype :: RemoteTypeA a -- For testing, makes a version of this remote that is not diff --git a/Utility/DirWatcher/FSEvents.hs b/Utility/DirWatcher/FSEvents.hs --- a/Utility/DirWatcher/FSEvents.hs +++ b/Utility/DirWatcher/FSEvents.hs @@ -70,7 +70,7 @@ scan d = unless (ignoredPath ignored d) $ -- Do not follow symlinks when scanning. -- This mirrors the inotify startup scan behavior. - mapM_ go =<< dirContentsRecursiveSkipping (const False) False d + mapM_ go =<< emptyWhenDoesNotExist (dirContentsRecursiveSkipping (const False) False d) where go f | ignoredPath ignored f = noop diff --git a/Utility/DirWatcher/Win32Notify.hs b/Utility/DirWatcher/Win32Notify.hs --- a/Utility/DirWatcher/Win32Notify.hs +++ b/Utility/DirWatcher/Win32Notify.hs @@ -43,7 +43,7 @@ runhook h s = maybe noop (\a -> a (filePath evt) s) (h hooks) scan d = unless (ignoredPath ignored d) $ - mapM_ go =<< dirContentsRecursiveSkipping (const False) False d + mapM_ go =<< emptyWhenDoesNotExist (dirContentsRecursiveSkipping (const False) False d) where go f | ignoredPath ignored f = noop diff --git a/Utility/Directory.hs b/Utility/Directory.hs --- a/Utility/Directory.hs +++ b/Utility/Directory.hs @@ -1,6 +1,6 @@ {- directory traversal and manipulation - - - Copyright 2011-2020 Joey Hess + - Copyright 2011-2023 Joey Hess - - License: BSD-2-clause -} @@ -43,14 +43,26 @@ - - Does not follow symlinks to other subdirectories. - - - When the directory does not exist, no exception is thrown, - - instead, [] is returned. -} + - Throws exception if the directory does not exist or otherwise cannot be + - accessed. However, does not throw exceptions when subdirectories cannot + - be accessed (the use of unsafeInterleaveIO would make it difficult to + - trap such exceptions). + -} dirContentsRecursive :: FilePath -> IO [FilePath] dirContentsRecursive = dirContentsRecursiveSkipping (const False) True {- Skips directories whose basenames match the skipdir. -} dirContentsRecursiveSkipping :: (FilePath -> Bool) -> Bool -> FilePath -> IO [FilePath] -dirContentsRecursiveSkipping skipdir followsubdirsymlinks topdir = go [topdir] +dirContentsRecursiveSkipping skipdir followsubdirsymlinks topdir + | skipdir (takeFileName topdir) = return [] + | otherwise = do + -- Get the contents of the top directory outside of + -- unsafeInterleaveIO, which allows throwing exceptions if + -- it cannot be accessed. + (files, dirs) <- collect [] [] + =<< dirContents topdir + files' <- go dirs + return (files ++ files') where go [] = return [] go (dir:dirs) @@ -79,9 +91,19 @@ {- Gets the directory tree from a point, recursively and lazily, - with leaf directories **first**, skipping any whose basenames - - match the skipdir. Does not follow symlinks. -} + - match the skipdir. Does not follow symlinks. + - + - Throws exception if the directory does not exist or otherwise cannot be + - accessed. However, does not throw exceptions when subdirectories cannot + - be accessed (the use of unsafeInterleaveIO would make it difficult to + - trap such exceptions). + -} dirTreeRecursiveSkipping :: (FilePath -> Bool) -> FilePath -> IO [FilePath] -dirTreeRecursiveSkipping skipdir topdir = go [] [topdir] +dirTreeRecursiveSkipping skipdir topdir + | skipdir (takeFileName topdir) = return [] + | otherwise = do + subdirs <- filterM isdir =<< dirContents topdir + go [] subdirs where go c [] = return c go c (dir:dirs) @@ -92,6 +114,12 @@ =<< catchDefaultIO [] (dirContents dir) go (subdirs++dir:c) dirs isdir p = isDirectory <$> R.getSymbolicLinkStatus (toRawFilePath p) + +{- When the action fails due to the directory not existing, returns []. -} +emptyWhenDoesNotExist :: IO [a] -> IO [a] +emptyWhenDoesNotExist a = tryWhenExists a >>= return . \case + Just v -> v + Nothing -> [] {- Use with an action that removes something, which may or may not exist. - diff --git a/Utility/Monad.hs b/Utility/Monad.hs --- a/Utility/Monad.hs +++ b/Utility/Monad.hs @@ -12,6 +12,7 @@ getM, anyM, allM, + partitionM, untilTrue, ifM, (<||>), @@ -44,6 +45,13 @@ allM :: Monad m => (a -> m Bool) -> [a] -> m Bool allM _ [] = return True allM p (x:xs) = p x <&&> allM p xs + +partitionM :: Monad m => (a -> m Bool) -> [a] -> m ([a], [a]) +partitionM _ [] = return ([], []) +partitionM p (x:xs) = do + r <- p x + (as, bs) <- partitionM p xs + return $ if r then (x:as, bs) else (as, x:bs) {- Runs an action on values from a list until it succeeds. -} untilTrue :: Monad m => [a] -> (a -> m Bool) -> m Bool diff --git a/Utility/Url.hs b/Utility/Url.hs --- a/Utility/Url.hs +++ b/Utility/Url.hs @@ -9,7 +9,6 @@ {-# LANGUAGE RankNTypes #-} {-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE BangPatterns #-} -{-# LANGUAGE CPP #-} module Utility.Url ( newManager, @@ -33,8 +32,6 @@ downloadConduit, sinkResponseFile, downloadPartial, - parseURIPortable, - parseURIRelaxed, matchStatusCodeException, matchHttpExceptionContent, BasicAuth(..), @@ -52,6 +49,7 @@ import Utility.IPAddress import qualified Utility.RawFilePath as R import Utility.Hash (IncrementalVerifier(..)) +import Utility.Url.Parse import Network.URI import Network.HTTP.Types @@ -72,9 +70,6 @@ import Data.Either import Data.Conduit import Text.Read -#ifdef mingw32_HOST_OS -import qualified System.FilePath.Windows as PW -#endif type URLString = String @@ -612,30 +607,6 @@ then Just <$> brReadSome (responseBody resp) n else return Nothing -{- On unix this is the same as parseURI. But on Windows, - - it can parse urls such as file:///C:/path/to/file - - parseURI normally parses that as a path /C:/path/to/file - - and this simply removes the excess leading slash when there is a - - drive letter after it. -} -parseURIPortable :: URLString -> Maybe URI -#ifndef mingw32_HOST_OS -parseURIPortable = parseURI -#else -parseURIPortable s - | "file:" `isPrefixOf` s = do - u <- parseURI s - return $ case PW.splitDirectories (uriPath u) of - (p:d:_) | all PW.isPathSeparator p && PW.isDrive d -> - u { uriPath = dropWhile PW.isPathSeparator (uriPath u) } - _ -> u - | otherwise = parseURI s -#endif - -{- Allows for spaces and other stuff in urls, properly escaping them. -} -parseURIRelaxed :: URLString -> Maybe URI -parseURIRelaxed s = maybe (parseURIRelaxed' s) Just $ - parseURIPortable $ escapeURIString isAllowedInURI s - {- Generate a http-conduit Request for an URI. This is able - to deal with some urls that parseRequest would usually reject. -} @@ -648,23 +619,6 @@ | uriPort ua == ":" -> parseRequest $ show $ u { uriAuthority = Just $ ua { uriPort = "" } } _ -> parseRequest (show u) - -{- Some characters like '[' are allowed in eg, the address of - - an uri, but cannot appear unescaped further along in the uri. - - This handles that, expensively, by successively escaping each character - - from the back of the url until the url parses. - -} -parseURIRelaxed' :: URLString -> Maybe URI -parseURIRelaxed' s = go [] (reverse s) - where - go back [] = parseURI back - go back (c:cs) = case parseURI (escapeURIString isAllowedInURI (reverse (c:cs)) ++ back) of - Just u -> Just u - Nothing -> go (escapeURIChar escapemore c ++ back) cs - - escapemore '[' = False - escapemore ']' = False - escapemore c = isAllowedInURI c hAcceptEncoding :: CI.CI B.ByteString hAcceptEncoding = "Accept-Encoding" diff --git a/Utility/Url/Parse.hs b/Utility/Url/Parse.hs new file mode 100644 --- /dev/null +++ b/Utility/Url/Parse.hs @@ -0,0 +1,64 @@ +{- Url parsing. + - + - Copyright 2011-2023 Joey Hess + - + - License: BSD-2-clause + -} + +{-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE RankNTypes #-} +{-# LANGUAGE FlexibleContexts #-} +{-# LANGUAGE BangPatterns #-} +{-# LANGUAGE CPP #-} + +module Utility.Url.Parse ( + parseURIPortable, + parseURIRelaxed, +) where + +import Network.URI +#ifdef mingw32_HOST_OS +import Data.List +import qualified System.FilePath.Windows as PW +#endif + +{- On unix this is the same as parseURI. But on Windows, + - it can parse urls such as file:///C:/path/to/file + - parseURI normally parses that as a path /C:/path/to/file + - and this simply removes the excess leading slash when there is a + - drive letter after it. -} +parseURIPortable :: String -> Maybe URI +#ifndef mingw32_HOST_OS +parseURIPortable = parseURI +#else +parseURIPortable s + | "file:" `isPrefixOf` s = do + u <- parseURI s + return $ case PW.splitDirectories (uriPath u) of + (p:d:_) | all PW.isPathSeparator p && PW.isDrive d -> + u { uriPath = dropWhile PW.isPathSeparator (uriPath u) } + _ -> u + | otherwise = parseURI s +#endif + +{- Allows for spaces and other stuff in urls, properly escaping them. -} +parseURIRelaxed :: String -> Maybe URI +parseURIRelaxed s = maybe (parseURIRelaxed' s) Just $ + parseURIPortable $ escapeURIString isAllowedInURI s + +{- Some characters like '[' are allowed in eg, the address of + - an uri, but cannot appear unescaped further along in the uri. + - This handles that, expensively, by successively escaping each character + - from the back of the url until the url parses. + -} +parseURIRelaxed' :: String -> Maybe URI +parseURIRelaxed' s = go [] (reverse s) + where + go back [] = parseURI back + go back (c:cs) = case parseURI (escapeURIString isAllowedInURI (reverse (c:cs)) ++ back) of + Just u -> Just u + Nothing -> go (escapeURIChar escapemore c ++ back) cs + + escapemore '[' = False + escapemore ']' = False + escapemore c = isAllowedInURI c diff --git a/doc/git-annex-add.mdwn b/doc/git-annex-add.mdwn deleted file mode 100644 --- a/doc/git-annex-add.mdwn +++ /dev/null @@ -1,137 +0,0 @@ -# NAME - -git-annex add - adds files to the git annex - -# SYNOPSIS - -git annex add `[path ...]` - -# DESCRIPTION - -Adds the specified files to the annex. If a directory is specified, -acts on all files inside the directory and its subdirectories. -If no path is specified, adds files from the current directory and below. - -Files that are already checked into git and are unmodified, or that -git has been configured to ignore will be silently skipped. - -If annex.largefiles is configured (in git config, gitattributes, or -git-annex config), and does not match a file, `git annex add` will behave -the same as `git add` and add the non-large file directly to the git -repository, instead of to the annex. (By default dotfiles are assumed to -not be large, and are added directly to git, but annex.dotfiles can be -configured to annex those too.) See the git-annex manpage for documentation -of these and other configuration settings. - -By default, large files are added to the annex in locked form, which -prevents further modification of their content until -unlocked by [[git-annex-unlock]](1). (This is not the case however -when a repository is in a filesystem not supporting symlinks.) -The annex.addunlocked git config (and git-annex config) can be used to -change this behavior. - -This command can also be used to add symbolic links, both symlinks to -annexed content, and other symlinks. - -# EXAMPLES - - # git annex add foo bar - add foo ok - add bar ok - # git commit -m added - -# OPTIONS - -* `--no-check-gitignore` - - Add gitignored files. - -* `--force-large` - - Treat all files as large files, ignoring annex.largefiles and annex.dotfiles - configuration, and add to the annex. - -* `--force-small` - - Treat all files as small files, ignoring annex.largefiles and annex.dotfiles - and annex.addsmallfiles configuration, and add to git. - -* `--backend` - - Specifies which key-value backend to use. - -* file matching options - - Many of the [[git-annex-matching-options]](1) - can be used to specify files to add. - - For example: `--largerthan=1GB` - -* `--jobs=N` `-JN` - - Adds multiple files in parallel. This may be faster. - For example: `-J4` - - Setting this to "cpus" will run one job per CPU core. - -* `--update` `-u` - - Like `git add --update`, this does not add new files, but any updates - to tracked files will be added to the index. - -* `--dry-run` - - Output what would be done for each file, but avoid making any changes. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-progress` - - Include progress objects in JSON output. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* `--batch` - - Enables batch mode, in which a file to add is read in a line from stdin, - the file is added, and repeat. - - Note that if a file is skipped (due to not existing, being gitignored, - already being in git, or doesn't meet the matching options), - an empty line will be output instead of the normal output produced - when adding a file. - -* `-z` - - Makes the `--batch` input be delimited by nulls instead of the usual - newlines. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-unlock]](1) - -[[git-annex-lock]](1) - -[[git-annex-undo]](1) - -[[git-annex-import]](1) - -[[git-annex-unannex]](1) - -[[git-annex-reinject]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-addunused.mdwn b/doc/git-annex-addunused.mdwn deleted file mode 100644 --- a/doc/git-annex-addunused.mdwn +++ /dev/null @@ -1,42 +0,0 @@ -# NAME - -git-annex addunused - add back unused files - -# SYNOPSIS - -git annex addunused `[number|range ...]` - -# DESCRIPTION - -Adds back files for the content corresponding to the numbers or ranges, -as listed by the last `git annex unused`. - -The files will have names starting with "unused." - -# OPTIONS - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* The [[git-annex-common-options]](1) can also be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-add]](1) - -[[git-annex-unused]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-addurl.mdwn b/doc/git-annex-addurl.mdwn deleted file mode 100644 --- a/doc/git-annex-addurl.mdwn +++ /dev/null @@ -1,166 +0,0 @@ -# NAME - -git-annex addurl - add urls to annex - -# SYNOPSIS - -git annex addurl `[url ...]` - -# DESCRIPTION - -Downloads each url to its own file, which is added to the annex. - -When `yt-dlp` is installed, it can be used to check for a video -embedded in a web page at the url, and that is added to the annex instead. -(However, this is disabled by default as it can be a security risk. -See the documentation of annex.security.allowed-ip-addresses -in [[git-annex]](1) for details.) - -Special remotes can add other special handling of particular urls. For -example, the bittorrent special remotes makes urls to torrent files -(including magnet links) download the content of the torrent, -using `aria2c`. - -Normally the filename is based on the full url, so will look like -"www.example.com_dir_subdir_bigfile". In some cases, addurl is able to -come up with a better filename based on other information. Options can also -be used to get better filenames. - -# OPTIONS - -* `--fast` - - Avoid immediately downloading the url. The url is still checked - (via HEAD) to verify that it exists, and to get its size if possible. - -* `--relaxed` - - Don't immediately download the url, and avoid storing the size of the - url's content. This makes git-annex accept whatever content is there - at a future point. - - This is the fastest option, but it still has to access the network - to check if the url contains embedded media. When adding large numbers - of urls, using `--relaxed --raw` is much faster. - -* `--raw` - - Prevent special handling of urls by yt-dlp, bittorrent, and other - special remotes. This will for example, make addurl - download the .torrent file and not the contents it points to. - -* `--no-raw` - - Require content pointed to by the url to be downloaded using yt-dlp - or a special remote, rather than the raw content of the url. if that - cannot be done, the add will fail. - -* `--file=name` - - Use with a filename that does not yet exist to add a new file - with the specified name and the content downloaded from the url. - - If the file already exists, addurl will record that it can be downloaded - from the specified url(s). - -* `--preserve-filename` - - When the web server (or torrent, etc) provides a filename, use it as-is, - avoiding sanitizing unusual characters, or truncating it to length, or any - other modifications. - - git-annex will still check the filename for safety, and if the filename - has a security problem such as path traversal or a control character, - it will refuse to add it. - -* `--pathdepth=N` - - Rather than basing the filename on the whole url, this causes a path to - be constructed, starting at the specified depth within the path of the - url. - - For example, adding the url http://www.example.com/dir/subdir/bigfile - with `--pathdepth=1` will use "dir/subdir/bigfile", - while `--pathdepth=3` will use "bigfile". - - It can also be negative; `--pathdepth=-2` will use the last - two parts of the url. - -* `--prefix=foo` `--suffix=bar` - - Use to adjust the filenames that are created by addurl. For example, - `--suffix=.mp3` can be used to add an extension to the file. - -* `--no-check-gitignore` - - By default, gitignores are honored and it will refuse to download an - url to a file that would be ignored. This makes such files be added - despite any ignores. - -* `--jobs=N` `-JN` - - Enables parallel downloads when multiple urls are being added. - For example: `-J4` - - Setting this to "cpus" will run one job per CPU core. - -* `--batch` - - Enables batch mode, in which lines containing urls to add are read from - stdin. - -* `-z` - - Makes the `--batch` input be delimited by nulls instead of the usual - newlines. - -* `--with-files` - - When batch mode is enabled, makes it parse lines of the form: "$url $file" - - That adds the specified url to the specified file, downloading its - content if the file does not yet exist; the same as - `git annex addurl $url --file $file` - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-progress` - - Include progress objects in JSON output. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* `--backend` - - Specifies which key-value backend to use. - -* Also the [[git-annex-common-options]](1) can be used. - -# CAVEATS - -If annex.largefiles is configured, and does not match a file, `git annex -addurl` will add the non-large file directly to the git repository, -instead of to the annex. However, this is not done when --fast or --relaxed -is used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-rmurl]](1) - -[[git-annex-registerurl]](1) - -[[git-annex-importfeed]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-adjust.mdwn b/doc/git-annex-adjust.mdwn deleted file mode 100644 --- a/doc/git-annex-adjust.mdwn +++ /dev/null @@ -1,137 +0,0 @@ -# NAME - -git-annex adjust - enter an adjusted branch - -# SYNOPSIS - -git annex adjust `--unlock|--lock|--fix|--hide-missing [--unlock|--lock|--fix]|--unlock-present` - -# DESCRIPTION - -Enters an adjusted form of the current branch. The annexed files will -be treated differently. For example with --unlock all annexed files will -be unlocked. - -The adjusted branch will have a name like "adjusted/master(unlocked)". -Since it's a regular git branch, you can use `git checkout` to switch -back to the original branch at any time. - -This allows changing how annexed files are handled, without making changes -to a public branch with commands like `git-annex unlock`. - -While in the adjusted branch, you can use git-annex and git commands as -usual. Any commits that you make will initially only be made to the -adjusted branch. - -To propagate commits from the adjusted branch back to the original branch, -and to other repositories, as well as to merge in changes from other -repositories, run `git annex sync`. This will propagate changes that you've -made such as adding/deleting files, but will not propagate the adjustments -made by this command. - -When in an adjusted branch, using `git merge otherbranch` is often not -ideal, because merging a non-adjusted branch may lead to unnecessary -merge conflicts, or add files in non-adjusted form. To avoid those -problems, use `git annex merge otherbranch`. - -Re-running this command with the same options -while inside the adjusted branch will update the adjusted branch -as necessary (eg for `--hide-missing` and `--unlock-present`), -and will also propagate commits back to the original branch. - -# OPTIONS - -* `--unlock` - - Unlock all annexed files in the adjusted branch. This allows - annexed files to be modified. - - Normally, unlocking a file requires a copy to be made of its content, - so that its original content is preserved, while the copy can be modified. - To use less space, annex.thin can be set to true before running this - command; this makes a hard link to the content be made instead of a copy. - (When supported by the file system.) While this can save considerable - disk space, any modification made to a file will cause the old version of the - file to be lost from the local repository. So, enable annex.thin with care. - - When in an adjusted unlocked branch, `git annex add` will add files - unlocked instead of the default behavior of adding them locked. - -* `--lock` - - Lock all annexed files in the adjusted branch. This may be preferred - by those who like seeing broken symlinks when the content of an - annexed file is not present. - - When in an adjusted locked branch, `git annex add` will add files locked, - as usual. However, `git add` (and `git commit -a` etc) still add files - unlocked. This is because it's not possible for those git commands to - add files locked. - -* `--fix` - - Fix the symlinks to annexed files to point to the local git annex - object directory. This can be useful if a repository is checked out in an - unusual way that prevents the symlinks committed to git from pointing at - the annex objects. - -* `--hide-missing` - - Only include annexed files in the adjusted branch when their content - is present. - - The adjusted branch is not immediately changed when content availability - changes, so if you `git annex drop` files, they will become broken - links in the usual way. And when files that were missing are copied into the - repository from elsewhere, they won't immediatly become visible in the - branch. - - To update the adjusted branch to reflect changes to content availability, - run `git annex adjust --hide-missing` again. Or, to automate updates, - set the `annex.adjustedbranchrefresh` config. - - Despite missing files being hidden, `git annex sync --content` will - still operate on them, and can be used to download missing - files from remotes. It also updates the adjusted branch after - transferring content. - - This option can be combined with --unlock, --lock, or --fix. - -* `--unlock-present` - - Unlock files whose content is present, and lock files whose content is - missing. This provides the benefits of working with unlocked files, - but makes it easier to see when the content of a file is not missing, - since it will be a broken symlink. - - The adjusted branch is not immediately changed when content availability - changes, so when you `git annex get` files, they will remain locked. - And when you `git annex drop` files, they will remain locked and so will - not be broken symlinks. - - To update the adjusted branch to reflect changes to content availability, - run `git annex adjust --unlock-present` again. Or, to automate updates, - set the `annex.adjustedbranchrefresh` config. Or use `git-annex sync - --content`, which updates the branch after transferring content. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-unlock]](1) - -[[git-annex-lock]](1) - -[[git-annex-upgrade]](1) - -[[git-annex-sync]](1) - -[[git-annex-view]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-assist.mdwn b/doc/git-annex-assist.mdwn deleted file mode 100644 --- a/doc/git-annex-assist.mdwn +++ /dev/null @@ -1,66 +0,0 @@ -# NAME - -git-annex assist - add files and sync changes with remotes - -# SYNOPSIS - -git annex assist `[remote ...]` - -# DESCRIPTION - -This command assists you in checking files into the repository -and syncing with remotes. It's the simplest possible way to use git-annex -at the command line, since only this one command needs to be run on a -regular basis. - -This command first adds any new files to the repository, and commits those -as well as any modified files. Then it does the equivilant of running -[[git-annex-pull](1) followed by [[git-annex-push]](1). - -This command operates on all files in the whole working tree, -even when ran in a subdirectory. To limit it to operating on files in a -subdirectory, use the `--content-of` option. - -To block some files from being added to the repository, use `.gitignore` -files. - -By default, all files that are added are added to the annex, the same -as when you run `git annex add`. If you configure annex.largefiles, -files that it does not match will instead be added with `git add`. - -# OPTIONS - -* `--message=msg` `-m msg` - - Use this option to specify a commit message. - -* `--content-of=path` `-C path` - - Only add, pull, and push files in the given path. - - This option can be repeated multiple times with different paths. - -* 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-add]](1) - -[[git-annex-pull]](1) - -[[git-annex-push]](1) - -[[git-annex-sync]](1) - -[[git-annex-assistant]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-assistant.mdwn b/doc/git-annex-assistant.mdwn deleted file mode 100644 --- a/doc/git-annex-assistant.mdwn +++ /dev/null @@ -1,72 +0,0 @@ -# NAME - -git-annex assistant - daemon to add files and automatically sync changes - -# SYNOPSIS - -git annex assistant - -# DESCRIPTION - -Watches for changes to files in the current directory and its subdirectories, -and automatically syncs them to other remotes. This includes adding new -files. New files published to remotes by others are also automatically -downloaded. - -By default, all new files in the directory will be added to the repository. -(Including dotfiles.) To block some files from being added, use -`.gitignore` files. - -By default, all files that are added are added to the annex, the same -as when you run `git annex add`. If you configure annex.largefiles, -files that it does not match will instead be added with `git add`. - -# OPTIONS - -* `--autostart` - - Automatically starts the assistant running in each repository listed - in the file `~/.config/git-annex/autostart` - - This is typically started at boot, or when you log in. - -* `--startdelay=N` - - Wait N seconds before running the startup scan. This process can - be expensive and you may not want to run it immediately upon login. - - When --autostart is used, defaults to --startdelay=5. - -* `--foreground` - - Avoid forking to the background. - -* `--stop` - - Stop a running daemon in the current repository. - -* `--autostop` - - The complement to --autostart; stops all running daemons in the - repositories listed in the autostart file. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-watch]](1) - -[[git-annex-assist]](1) - -[[git-annex-schedule]](1) - -For more details about the git-annex assistant, see - - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-backends.mdwn b/doc/git-annex-backends.mdwn deleted file mode 100644 --- a/doc/git-annex-backends.mdwn +++ /dev/null @@ -1,24 +0,0 @@ -# NAME - -git-annex-backends - key/value backends for git-annex - -# DESCRIPTION - -The "backend" in git-annex controls how a key is generated from a file's -content and/or filesystem metadata. Most backends are different kinds of -hashes. A single repository can use different backends for different files. - -For a list of available backends, see `git-annex version`. For more -details, see - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - - - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-calckey.mdwn b/doc/git-annex-calckey.mdwn deleted file mode 100644 --- a/doc/git-annex-calckey.mdwn +++ /dev/null @@ -1,47 +0,0 @@ -# NAME - -git-annex calckey - calculate key for a file - -# SYNOPSIS - -git annex calckey `[file ...]` - -# DESCRIPTION - -This plumbing-level command calculates the key that would be used -to refer to a file. The file is not added to the annex by this command. -The key is output to stdout. - -The backend used is the one from the annex.backend configuration -setting, which can be overridden by the --backend option. -For example, to force use of the SHA1 backend: - - git annex calckey --backend=SHA1 file - -# OPTIONS - -* `--backend=name` - - Specifies which key-value backend to use. - -* `--batch` - - Enable batch mode, in which a line containing the filename is read from - stdin, the key is output to stdout (with a trailing newline), and repeat. - -* `-z` - - Makes the `--batch` input be delimited by nulls instead of the usual - newlines. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-checkpresentkey.mdwn b/doc/git-annex-checkpresentkey.mdwn deleted file mode 100644 --- a/doc/git-annex-checkpresentkey.mdwn +++ /dev/null @@ -1,40 +0,0 @@ -# NAME - -git-annex checkpresentkey - check if key is present in remote - -# SYNOPSIS - -git annex checkpresentkey `key` `[remote]` - -# DESCRIPTION - -This plumbing-level command verifies if the specified key's content -is present in the specified remote. - -When no remote is specified, it verifies if the key's content is present -in any accessible remotes. - -Exits 0 if the content is verified present in the remote, or 1 if it is -verified to not be present in the remote. If there is a problem, -the special exit code 100 is used, and an error message is output to stderr. - -# OPTIONS - -* `--batch` - - Enables batch mode. In this mode, the `key` is not specified at the - command line, but the `remote` may still be. Lines containing keys are - read from stdin, and a line is output with "1" if the key is verified to - be present, and "0" otherwise. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-config.mdwn b/doc/git-annex-config.mdwn deleted file mode 100644 --- a/doc/git-annex-config.mdwn +++ /dev/null @@ -1,238 +0,0 @@ -# NAME - -git-annex config - configuration stored in git-annex branch - -# SYNOPSIS - -git annex config --set name value - -git annex config --get name - -git annex config --unset name - -git annex config --show-origin name - -# DESCRIPTION - -Set or get configuration settings stored in the git-annex branch. - -Unlike `git config` settings, these settings can be seen -in all clones of the repository, once they have gotten their -git-annex branches in sync. - -These settings can be overridden on a per-repository basis using -`git config`. - -git-annex does not check the git-annex branch for all the `git config` -settings that affect it (which are listed on the git-annex man page -CONFIGURATION section). Only a few make sense to be able to set such -that all clones of a repository see the setting, and so git-annex only -looks for these. - -# SUPPORTED SETTINGS - -* `annex.numcopies` - - Tells git-annex how many copies it should preserve of files, over all - repositories. The default is 1. - - When git-annex is asked to drop a file, it first verifies that the - number of copies can be satisfied among all the other - repositories that have a copy of the file. - - In unusual situations, involving special remotes that do not support - locking, and concurrent drops of the same content from multiple - repositories, git-annex may violate the numcopies setting. It still - guarantees at least 1 copy is preserved. This can be configured by - setting annex.mincopies. - - This is the same setting that the [[git-annex-numcopies]](1) command - configures. It can be overridden on a per-file basis - by the annex.numcopies setting in `.gitattributes` files. - -* `annex.mincopies` - - Tells git-annex how many copies it is required to preserve of files, - over all repositories. The default is 1. - - This supplements the annex.numcopies setting. - In unusual situations, involving special remotes that do not support - locking, and concurrent drops of the same content from multiple - repositories, git-annex may violate the numcopies setting. - In these unusual situations, git-annex ensures that the number of copies - never goes below mincopies. - - It is a good idea to not only rely on only setting mincopies. Set - numcopies as well, to a larger number, and keep mincopies at the - bare minimum you're comfortable with. Setting mincopies to a large - number, rather than setting numcopies will in some cases prevent - droping content in entirely safe situations. - - This is the same setting that the [[git-annex-mincopies]](1) command - configures. It can be overridden on a per-file basis - by the annex.mincopies setting in `.gitattributes` files. - -* `annex.largefiles` - - Used to configure which files are large enough to be added to the annex. - It is an expression that matches the large files, eg - "`include=*.mp3 or largerthan(500kb)`". - See [[git-annex-matching-expression]](1) for details on the syntax. - - This configures the behavior of both git-annex and git when adding - files to the repository. By default, `git-annex add` adds all files - to the annex (except dotfiles), and `git add` adds files to git - (unless they were added to the annex previously). - When annex.largefiles is configured, both - `git annex add` and `git add` will add matching large files to the - annex, and the other files to git. - - Other git-annex commands also honor annex.largefiles, including - `git annex import`, `git annex addurl`, `git annex importfeed`, - `git-annex assist`, and the `git-annex assistant`. - - This sets a default, which can be overridden by annex.largefiles - attributes in `.gitattributes` files, or by `git config`. - -* `annex.dotfiles` - - Normally, dotfiles are assumed to be files like .gitignore, - whose content should always be part of the git repository, so - they will not be added to the annex. Setting annex.dotfiles to true - makes dotfiles be added to the annex the same as any other file. - - This sets a default, which can be overridden by annex.dotfiles - in `git config`. - -* `annex.addunlocked` - - Commands like `git-annex add` default to adding files to the repository - in locked form. This can make them add the files in unlocked form, - the same as if [[git-annex-unlock]](1) were run on the files. - - This can be set to "true" to add everything unlocked, or it can be a more - complicated expression that matches files by name, size, or content. See - [[git-annex-matching-expression]](1) for details. - - This sets a default, which can be overridden by annex.addunlocked - in `git config`. - -* `annex.autocommit` - - Set to false to prevent the `git-annex assistant`, `git-annex assist` - and `git-annex sync` from automatically committing changes to files - in the repository. - - This sets a default, which can be overridden by annex.autocommit - in `git config`. - -* `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 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 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`, `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`. - -* `annex.securehashesonly` - - Set to true to indicate that the repository should only use - cryptographically secure hashes (SHA2, SHA3) and not insecure - hashes (MD5, SHA1) for content. - - When this is set, the contents of files using cryptographically - insecure hashes will not be allowed to be added to the repository. - - Also, `git-annex fsck` will complain about any files present in - the repository that use insecure hashes. - - Note that this is only read from the git-annex branch by - `git annex init`, and is copied to the corresponding git config setting. - So, changes to the value in the git-annex branch won't affect a - repository once it has been initialized. - -# OPTIONS - -* `--set name value` - - Set a value. - -* `--get name` - - Get a value. - -* `--unset` - - Unset a value. - -* `--show-origin name` - - Explain where the value is configured, whether in the git-annex branch, - or in a `git config` file, or `.gitattributes` file. When a value is - configured in multiple places, displays the place and the value that - will be used. - - Note that the parameter can be the name of one of the settings listed - above, but also any other configuration setting supported by git-annex. - For example, "annex.backend" cannot be set in the git-annex branch, but - it can be set in `.gitattributes` or `git config` and this option can - explain which setting will be used for it. - -* `--for-file file` - - Can be used in combination with `--show-origin` to specify what - filename to check for in `.gitattributes`. - -* Also the [[git-annex-common-options]](1) can be used. - -# EXAMPLE - -Suppose you want to prevent git annex sync from committing changes -to files, so a manual git commit workflow is used in all clones of the -repository. Then run: - - git annex config --set annex.autocommit false - -If you want to override that in a partiticular clone, just use git config -in the clone: - - git config annex.autocommit true - -And to get back to the default behavior: - - git annex config --unset annex.autocommit - -# SEE ALSO - -[[git-annex]](1) - -git-config(1) - -[[git-annex-vicfg]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-configremote.mdwn b/doc/git-annex-configremote.mdwn deleted file mode 100644 --- a/doc/git-annex-configremote.mdwn +++ /dev/null @@ -1,41 +0,0 @@ -# NAME - -git-annex configremote - changes special remote configuration - -# SYNOPSIS - -git annex configemote `name|uuid|desc [param=value ...]` - -# DESCRIPTION - -Changes the configuration of a special remote that was set up earlier -by `git-annex initremote`. The special remote does not need to be enabled -for use in the current repository, and this command will not enable it. - -This command can currently only be used to change the value of the -`autoenable` parameter, eg "autoenable=false". - -To change other parameters, use `git-annex enableremote` - -# OPTIONS - -Most options are not prefixed by a dash, and set parameters of the remote, -as shown above. - -Also, the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-initremote]](1) - -[[git-annex-configremote]](1) - -[[git-annex-renameremote]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-contentlocation.mdwn b/doc/git-annex-contentlocation.mdwn deleted file mode 100644 --- a/doc/git-annex-contentlocation.mdwn +++ /dev/null @@ -1,36 +0,0 @@ -# NAME - -git-annex contentlocation - looks up content for a key - -# SYNOPSIS - -git annex contentlocation `[key ...]` - -# DESCRIPTION - -This plumbing-level command looks up filename used to store the content -of a key. The filename is output to stdout. If the key's content is not -present in the local repository, nothing is output, and it exits nonzero. - -# OPTIONS - -* `--batch` - - Enable batch mode, in which a line containing the key is read from - stdin, the filename to its content is output to stdout (with a trailing - newline), and repeat. - - Note that if a key's content is not present, an empty line is output to - stdout instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-copy.mdwn b/doc/git-annex-copy.mdwn deleted file mode 100644 --- a/doc/git-annex-copy.mdwn +++ /dev/null @@ -1,146 +0,0 @@ -# NAME - -git-annex copy - copy content of files to/from another repository - -# SYNOPSIS - -git annex copy `[path ...] [--from=remote|--to=remote]` - -# DESCRIPTION - -Copies the content of files from or to another remote. - -With no parameters, operates on all annexed files in the current directory. -Paths of files or directories to operate on can be specified. - -# OPTIONS - -* `--from=remote` - - Copy the content of files from the specified - remote to the local repository. - - Any files that are not available on the remote will be silently skipped. - -* `--to=remote` - - Copy the content of files from the local repository - to the specified remote. - -* `--to=here` - - Copy the content of files from all reachable remotes to the local - repository. - -* `--from=remote1 --to=remote2` - - Copy the content of files that are in remote1 to remote2. - - This is implemented by first downloading the content from remote1 to the - local repository (if not already present), then sending it to remote2, and - then deleting the content from the local repository (if it was not present - to start with). - -* `--jobs=N` `-JN` - - Enables parallel transfers 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 when using --from with --to, twice this many jobs will - run at once, evenly split between the two remotes. - -* `--auto` - - Rather than copying all specified files, only copy those that don't yet have - the desired number of copies, or that are preferred content of the - destination repository. See [[git-annex-preferred-content]](1) - -* `--fast` - - When copying content to a remote, avoid a round trip to check if the remote - already has content. This can be faster, but might skip copying content - to the remote in some cases. - -* `--all` `-A` - - Rather than specifying a filename or path to copy, this option can be - used to copy all available versions of all files. - - This is the default behavior when running git-annex in a bare repository. - -* `--branch=ref` - - Operate on files in the specified branch or treeish. - -* `--unused` - - Operate on files found by last run of git-annex unused. - -* `--failed` - - Operate on files that have recently failed to be transferred. - -* `--key=keyname` - - Use this option to copy a specified key. - -* matching options - - The [[git-annex-matching-options]](1) - can be used to specify what to copy. - -* `--batch` - - Enables batch mode, in which lines containing names of files to copy - are read from stdin. - - As each specified file is processed, the usual progress output is - displayed. If a file's content does not need to be copied, or it does not - match specified matching options, or it is not an annexed file, - a blank line is output in response instead. - - Since the usual output while copying a file is verbose and not - machine-parseable, you may want to use --json in combination with - --batch. - -* `--batch-keys` - - This is like `--batch` but the lines read from stdin are parsed as keys. - -* `-z` - - Makes batch input be delimited by nulls instead of the usual newlines. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-progress` - - Include progress objects in JSON output. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-get]](1) - -[[git-annex-move]](1) - -[[git-annex-drop]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-dead.mdwn b/doc/git-annex-dead.mdwn deleted file mode 100644 --- a/doc/git-annex-dead.mdwn +++ /dev/null @@ -1,65 +0,0 @@ -# NAME - -git-annex dead - hide a lost repository or key - -# SYNOPSIS - -git annex dead `[repository ...] [--key somekey ...]` - -# DESCRIPTION - -This command exists to deal with situations where data has been lost, -and you know it has, and you want to stop being reminded of that fact. - -When a repository is specified, indicates that the repository has -been irretrievably lost, so it will not be listed in eg, `git annex info`. -Repositories can be specified using their remote name, their -description, or their UUID. (To undo, use `git-annex semitrust`.) - -When a key is specified, indicates that the content of that key has been -irretrievably lost. This makes the key be skipped when operating -on all keys with eg `--all`. -(To undo, add the key's content back to the repository, -by using eg, `git-annex reinject`.) - -# OPTIONS - -* `--key=somekey` - - Use to specify a key that is dead. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-trust]](1) - -[[git-annex-semitrust]](1) - -[[git-annex-untrust]](1) - -[[git-annex-renameremote]](1) - -[[git-annex-expire]](1) - -[[git-annex-fsck]](1) - -[[git-annex-reinject]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-describe.mdwn b/doc/git-annex-describe.mdwn deleted file mode 100644 --- a/doc/git-annex-describe.mdwn +++ /dev/null @@ -1,45 +0,0 @@ -# NAME - -git-annex describe - change description of a repository - -# SYNOPSIS - -git annex describe repository description - -# DESCRIPTION - -Changes the description of a repository. - -The repository to describe can be specified by git remote name or -by uuid. To change the description of the current repository, use -"here". - -Repository descriptions are displayed by git-annex in various places. -They are most useful when git-annex knows about a repository, but there is -no git remote corresponding to it. - -# OPTIONS - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-init]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-diffdriver.mdwn b/doc/git-annex-diffdriver.mdwn deleted file mode 100644 --- a/doc/git-annex-diffdriver.mdwn +++ /dev/null @@ -1,60 +0,0 @@ -# NAME - -git-annex diffdriver - git diff driver - -# SYNOPSIS - -git annex diffdriver --text [-- --opts --] - -git annex diffdriver `-- cmd --opts --` - -# DESCRIPTION - -Normally, `git diff` when run on annexed files displays the changes that -are staged in git, eg annex symlinks and pointers. This command allows -`git diff` to diff the content of annexed files instead. - -This command can be used either as a simple text differ, -or as a shim that runs an external git diff driver. - -If some of your annexed files are textual in form, and can be usefully -diffed with diff(1), you can configure git to use this command to diff -them, by configuring `.gitattributes` to contain eg `*.txt diff=annextextdiff` -and setting `git config diff.annextextdiff.command "git annex diffdriver --text"`. - -If your annexed files are not textual in form, you will need an external -diff driver program that is able to diff the file format(s) you use. -See git's documentation of `GIT_EXTERNAL_DIFF` and -gitattributes(5)'s documentation of external diff drivers. - -Normally, when using `git diff` with an external diff driver, it will not -see the contents of annexed files, since git passes to it the git-annex -symlinks or pointer files. This command works around the problem, by -running the real external diff driver, and passing it the paths to the -annexed content. Configure git to use "git-annex diffdriver -- cmd params --" -as the external diff driver, where cmd is the external diff -driver you want it to run, and params are any extra parameters to pass -to it. Note the trailing "--", which is required. - -For example, to use the j-c-diff program as the external diff driver, -set `GIT_EXTERNAL_DIFF="git-annex diffdriver -- j-c-diff --"` - -# OPTIONS - -To diff text files with diff(1), use the "--text" option. -To pass additional options to diff(1), use eg "--text -- --color --" - -To use an external diff driver command, the options must start with -"--" followed by the diff driver command, its options, and another "--" - -Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-direct.mdwn b/doc/git-annex-direct.mdwn deleted file mode 100644 --- a/doc/git-annex-direct.mdwn +++ /dev/null @@ -1,27 +0,0 @@ -# NAME - -git-annex direct - switch repository to direct mode (deprecated) - -# SYNOPSIS - -git annex direct - -# DESCRIPTION - -This used to switch a repository to use direct mode. -But direct mode is no longer used; git-annex automatically converts -direct mode repositories to v7 adjusted unlocked branches. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-indirect]](1) - -[[git-annex-adjust]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-drop.mdwn b/doc/git-annex-drop.mdwn deleted file mode 100644 --- a/doc/git-annex-drop.mdwn +++ /dev/null @@ -1,152 +0,0 @@ -# NAME - -git-annex drop - remove content of files from repository - -# SYNOPSIS - -git annex drop `[path ...]` - -# DESCRIPTION - -Drops the content of annexed files from this repository, when -possible. - -git-annex will refuse to drop content if it cannot verify it is -safe to do so. Usually this involves verifying that the content is stored -in some other repository. - -Content that is required to be stored in the repository will not be dropped -even if enough copies exist elsewhere. See [[git-annex-required]](1). - -With no parameters, tries to drop all annexed files in the current directory. -Paths of files or directories to drop can be specified. - -# EXAMPLES - - # git annex drop *.jpeg - drop photo1.jpg (checking origin...) ok - drop photo2.jpg (unsafe) - Could only verify the existence of 0 out of 1 necessary copies - - Rather than dropping this file, try using: git annex move - - (Use --force to override this check, or adjust numcopies.) - failed - drop photo3.jpg (checking origin...) ok - -# OPTIONS - -* `--from=remote` - - Rather than dropping the content of files in the local repository, - this option can specify a remote from which the files' - contents should be removed. - -* `--auto` - - Rather than trying to drop all specified files, drop only those that - are not preferred content of the repository, and avoid trying to drop - files when there are not enough other copies for the drop to be possible. - See [[git-annex-preferred-content]](1) - -* `--force` - - Use this option with care! It bypasses safety checks, and forces - git-annex to delete the content of the specified files, even from - the last repository that is storing their content. Data loss can - result from using this option. - -* `--all` `-A` - - Rather than specifying a filename or path to drop, this option can be - used to drop all available versions of all files. - - This is the default behavior when running git-annex drop in a bare - repository. - - Note that this bypasses checking the .gitattributes annex.numcopies - setting and required content settings. - -* `--branch=ref` - - Drop files in the specified branch or treeish. - - Note that this bypasses checking the .gitattributes annex.numcopies - setting and required content settings. - -* `--unused` - - Drop files found by last run of git-annex unused. - - Note that this bypasses checking the .gitattributes annex.numcopies - setting and required content settings. - -* `--key=keyname` - - Use this option to drop a specified key. - - Note that this bypasses checking the .gitattributes annex.numcopies - setting and required content settings. - -* matching options - - The [[git-annex-matching-options]](1) - can be used to specify what to drop. - -* `--jobs=N` `-JN` - - Runs multiple drop jobs in parallel. This is particularly useful - when git-annex has to contact remotes to check if it can drop files. - For example: `-J4` - - Setting this to "cpus" will run one job per CPU core. - -* `--batch` - - Enables batch mode, in which lines containing names of files to drop - are read from stdin. - - As each specified file is processed, the usual output is - displayed. If a file's content is not present, or it does not - match specified matching options, or it is not an annexed file, - a blank line is output in response instead. - -* `--batch-keys` - - This is like `--batch` but the lines read from stdin are parsed as keys. - - Note that this bypasses checking the .gitattributes annex.numcopies - setting and required content settings. - -* `-z` - - Makes the batch input be delimited by nulls - instead of the usual newlines. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-get]](1) - -[[git-annex-move]](1) - -[[git-annex-copy]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-dropkey.mdwn b/doc/git-annex-dropkey.mdwn deleted file mode 100644 --- a/doc/git-annex-dropkey.mdwn +++ /dev/null @@ -1,49 +0,0 @@ -# NAME - -git-annex dropkey - drops annexed content for specified keys - -# SYNOPSIS - -git annex dropkey `[key ...]` - -# DESCRIPTION - -This plumbing-level command drops the annexed data for the specified -keys from this repository. - -This can be used to drop content for arbitrary keys, which do not need -to have a file in the git repository pointing at them. - -Warning: This command does not check that enough other copies of the content -exist; using it can easily result in data loss. - -# OPTIONS - -* `--batch` - - Enables batch mode, in which lines containing keys to drop are read from - stdin. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-setkey]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-dropunused.mdwn b/doc/git-annex-dropunused.mdwn deleted file mode 100644 --- a/doc/git-annex-dropunused.mdwn +++ /dev/null @@ -1,65 +0,0 @@ -# NAME - -git-annex dropunused - drop unused file content - -# SYNOPSIS - -git annex dropunused `[number|range ...]` - -# DESCRIPTION - -Drops the data corresponding to the numbers, as listed by the last -`git annex unused` - -You can also specify ranges of numbers, such as "1-1000". -Or, specify "all" to drop all unused data. - -# OPTIONS - -* `--from=remote` - - Rather than dropping the unused files from the local repository, - drop them from the remote repository. - -* `--force` - - Use this option with care! It bypasses safety checks, and forces - git-annex to delete the content of the specified files, even from - the last repository that is storing their content. Data loss can - result from using this option. - -* `--jobs=N` `-JN` - - Runs multiple drop jobs in parallel. This is particularly useful - when git-annex has to contact remotes to check if it can drop content. - For example: `-J4` - - Setting this to "cpus" will run one job per CPU core. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-unused]](1) - -[[git-annex-drop]](1) - -[[git-annex-copy]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-edit.mdwn b/doc/git-annex-edit.mdwn deleted file mode 100644 --- a/doc/git-annex-edit.mdwn +++ /dev/null @@ -1,18 +0,0 @@ -# NAME - -git-annex unlock - unlock files for modification - -# SYNOPSIS - -git annex edit `[path ...]` - -# DESCRIPTION - -This is an alias for the `unlock` command; see [[git-annex-unlock]](1) -for details. - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-enable-tor.mdwn b/doc/git-annex-enable-tor.mdwn deleted file mode 100644 --- a/doc/git-annex-enable-tor.mdwn +++ /dev/null @@ -1,40 +0,0 @@ -# NAME - -git-annex enable-tor - enable tor hidden service - -# SYNOPSIS - -git annex enable-tor - -sudo git annex enable-tor $(id -u) - -# DESCRIPTION - -This command enables a tor hidden service for git-annex. - -It modifies `/etc/tor/torrc` to register the hidden service. If run as a -normal user, it will try to use sudo/su/etc to get root access to modify -that file. If you run it as root, pass it your non-root user id number, -as output by `id -u` - -After this command is run, `git annex remotedaemon` can be run to serve the -tor hidden service, and then `git-annex p2p --gen-addresses` can be run to -give other users access to your repository via the tor hidden service. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-p2p-auth]](1) - -[[git-annex-remotedaemon]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-enableremote.mdwn b/doc/git-annex-enableremote.mdwn deleted file mode 100644 --- a/doc/git-annex-enableremote.mdwn +++ /dev/null @@ -1,88 +0,0 @@ -# NAME - -git-annex enableremote - enables git-annex to use a remote - -# SYNOPSIS - -git annex enableremote `name|uuid|desc [param=value ...]` - -# DESCRIPTION - -Enables use of an existing remote in the current repository, -that was set up earlier by `git annex initremote` run in -another clone of the repository. - -When enabling a remote, specify the same name used when originally -setting up that remote with `git annex initremote`. Run -`git annex enableremote` without any name to get a list of -remote names. Or you can specify the uuid or description of the -remote. - -Some types of special remotes need parameters to be specified every time -they are enabled. For example, the directory special remote requires a -directory= parameter every time. The command will prompt for any required -parameters you leave out. - -This command can also be used to modify the configuration of an existing -special remote, by specifying new values for parameters that are -usually set when using initremote. (However, some settings such as -the as the encryption scheme cannot be changed once a special remote -has been created.) - -The GPG keys that an encrypted special remote is encrypted with can be -changed using the keyid+= and keyid-= parameters. These respectively -add and remove keys from the list. However, note that removing a key -does NOT necessarily prevent the key's owner from accessing data -in the encrypted special remote -(which is by design impossible, short of deleting the remote). - -One use-case of keyid-= is to replace a revoked key with -a new key: - - git annex enableremote mys3 keyid-=revokedkey keyid+=newkey - -Also, note that for encrypted special remotes using plain public-key -encryption (encryption=pubkey), adding or removing a key has NO effect -on files that have already been copied to the remote. Hence using -keyid+= and keyid-= with such remotes should be used with care, and -make little sense except in cases like the revoked key example above. - -If you get tired of manually enabling a special remote in each new clone, -you can pass "autoenable=true". Then when [[git-annex-init]](1) is run in -a new clone, it will will attempt to enable the special remote. Of course, -this works best when the special remote does not need anything special -to be done to get it enabled. - -(This command also can be used to enable a git remote that git-annex -has found didn't work before and gave up on using, setting -`remote..annex-ignore`.) - -# OPTIONS - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also, the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-initremote]](1) - -[[git-annex-configremote]](1) - -[[git-annex-renameremote]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-examinekey.mdwn b/doc/git-annex-examinekey.mdwn deleted file mode 100644 --- a/doc/git-annex-examinekey.mdwn +++ /dev/null @@ -1,91 +0,0 @@ -# NAME - -git-annex examinekey - prints information from a key - -# SYNOPSIS - -git annex examinekey `[key ...]` - -# DESCRIPTION - -This plumbing-level command is given a key, and prints information -that can be determined purely by looking at the key. - -# OPTIONS - -* `--format=value` - - Use custom output formatting. - - The value is a format string, in which '${var}' is expanded to the - value of a variable. To right-justify a variable with whitespace, - use '${var;width}' ; to left-justify a variable, use '${var;-width}'; - to escape unusual characters (including control characters) - in a variable, use '${escaped_var}' - - To generate a path from the top of the repository to the git-annex - object for a key, use ${objectpath}. To generate the value of a - git-annex pointer file for a key, use ${objectpointer}. - - These variables are also available for use in formats: ${key}, ${backend}, - ${bytesize}, ${humansize}, ${keyname}, ${hashdirlower}, ${hashdirmixed}, - ${mtime} (for the mtime field of a WORM key), ${file} (when a filename is - provided to examinekey). - - Also, '\\n' is a newline, '\\000' is a NULL, etc. - - The default output format is the same as `--format='${escapedkey}\\n'` - except when outputting to a terminal, control characters will be escaped. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* `--migrate-to-backend=backend` - - Attempt to migrate the input key to the new backend specified. If - successful, outputs information about the migrated key. Otherwise, - outputs information about the input key. - - This only does fast migrations; it will not re-hash the content of a key - or similar expensive operation. - - One way to use it is to add an extension to a key. - - git-annex examinekey SHA256--xxx --migrate-to-backend=SHA256E --filename=foo.tar.gz - - Or to remove the extension from a key: - - git-annex examinekey SHA256E-xxx.tar.gz --migrate-to-backend=SHA256 - -* `--filename=name` - - The name of a file associated with the key, eg a work tree file. - It does not need to exist. This is needed when using `--migrate-to-backend` - to add an extension to the key. - -* `--batch` - - Enable batch mode, in which a line containing a key is read from stdin, - the information about it is output to stdout, and repeat. - - In order to also provide the name of a file associated with the key, the - line can be in the format "$key $file" - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-expire.mdwn b/doc/git-annex-expire.mdwn deleted file mode 100644 --- a/doc/git-annex-expire.mdwn +++ /dev/null @@ -1,79 +0,0 @@ -# NAME - -git-annex expire - expire inactive repositories - -# SYNOPSIS - -git annex expire `[repository:]time ...` - -# DESCRIPTION - -This command expires repositories that have not performed some activity -within a specified time period. A repository is expired by marking it as -dead. De-expiration is also done; if a dead repository performed some -activity recently, it is marked as semitrusted again. - -This can be useful when it's not possible to keep track of the state -of repositories manually. For example, a distributed network of -repositories where nobody can directly access all the repositories to -check their status. - -The repository can be specified using the name of a remote, -or the description or uuid of the repository. - -The time is in the form "60d" or "1y". A time of "never" will disable -expiration. - -If a time is specified without a repository, it is used as the default -value for all repositories. Note that the current repository is never -expired. - -# OPTIONS - -* `--no-act` - - Print out what would be done, but not not actually expire or unexpire - any repositories. - -* `--activity=Name` - - Specify the activity that a repository must have performed to avoid being - expired. The default is any activity. - - Currently, the only activity that can be performed to avoid expiration - is --activity=Fsck which corresponds to `git annex fsck`. - Note that fscking a remote updates the expiration of the remote - repository, not the local repository. - - The first version of git-annex that recorded fsck activity was - 5.20150405. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-fsck]](1) - -[[git-annex-schedule]](1) - -[[git-annex-dead]](1) - -[[git-annex-semitrust]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-export.mdwn b/doc/git-annex-export.mdwn deleted file mode 100644 --- a/doc/git-annex-export.mdwn +++ /dev/null @@ -1,175 +0,0 @@ -# NAME - -git-annex export - export a tree of files to a special remote - -# SYNOPSIS - -git annex export `treeish --to remote` - -# DESCRIPTION - -Use this command to export a tree of files from a git-annex repository. - -Normally files are stored on a git-annex special remote named by their -keys. That is great for reliable data storage, but your filenames are -obscured. Exporting replicates the tree to the special remote as-is. - -Mixing key/value storage and exports in the same remote would be a mess and -so is not allowed. You have to configure a special remote with -`exporttree=yes` when initially setting it up with -[[git-annex-initremote]](1). - -The treeish to export can be the name of a git branch, or a tag, or any -other treeish accepted by git, including eg master:subdir to only export a -subdirectory from a branch. - -When the remote has a preferred content expression set by -[[git-annex-wanted]](1), the treeish is -filtered through it, excluding annexed files it does not want from -being exported to it. (Note that things in the expression like -"include=" match relative to the top of the treeish being exported.) - -Any files in the treeish that are stored on git will also be exported to -the special remote. - -Repeated exports are done efficiently, by diffing the old and new tree, -and transferring only the changed files, and renaming files as necessary. - -Exports can be interrupted and resumed. However, partially uploaded files -will be re-started from the beginning in most cases. - -Once content has been exported to a remote, commands like `git annex get` -can download content from there the same as from other remotes. However, -since an export is not a key/value store, git-annex has to do more -verification of content downloaded from an export. Some types of keys, -that are not based on checksums, cannot be downloaded from an export. -And, git-annex will never trust an export to retain the content of a key. - -However, some special remotes, notably S3, support keeping track of old -versions of files stored in them. If a special remote is set up to do -that, it can be used as a key/value store and the limitations in the above -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. - -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 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. -When a file on a special remote has been modified by software other than -git-annex, exporting to it will not overwrite the modified file, and the -export will not succeed. You can resolve this conflict by using -`git annex import`. - -(Some types of special remotes such as S3 with versioning may instead -let an export overwrite the modified file; then `git annex import` -will create a sequence of commits that includes the modified file, -so the overwritten modification is not lost.) - -# OPTIONS - -* `--to=remote` - - Specify the special remote to export to. - -* `--tracking` - - This is a deprecated way to set "remote..annex-tracking-branch". - Instead of using this option, you should just set the git configuration - yourself. - -* `--fast` - - This sets up an export of a tree, but avoids any expensive file uploads to - the remote. You can later run `git annex push` to upload - the files to the export. - -* `--jobs=N` `-JN` - - Exports multiple files in parallel. This may be faster. - For example: `-J4` - - Setting this to "cpus" will run one job per CPU core. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-progress` - - Include progress objects in JSON output. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# EXAMPLE - - git annex initremote myremote type=directory directory=/mnt/myremote \ - exporttree=yes encryption=none - git annex export master --to myremote - -After that, /mnt/myremote will contain the same tree of files as the master -branch does. - - git mv myfile subdir/myfile - git commit -m renamed - git annex export master --to myremote - -That updates /mnt/myremote to reflect the renamed file. - - git annex export master:subdir --to myremote - -That updates /mnt/myremote, to contain only the files in the "subdir" -directory of the master branch. - -# EXPORT CONFLICTS - -If two different git-annex repositories are both exporting different trees -to the same special remote, it's possible for an export conflict to occur. -This leaves the special remote with some files from one tree, and some -files from the other. Files in the special remote may have entirely the -wrong content as well. - -It's not possible for git-annex to detect when making an export will result -in an export conflict. The best way to avoid export conflicts is to either -only ever export to a special remote from a single repository, or to have a -rule about the tree that you export to the special remote. For example, if -you always export origin/master after pushing to origin, then an export -conflict can't happen. - -An export conflict can only be detected after the two git repositories -that produced it get back in sync. Then the next time you run `git annex -export`, it will detect the export conflict, and resolve it. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-initremote]](1) - -[[git-annex-import]](1) - -[[git-annex-push]](1) - -[[git-annex-preferred-content]](1) - -# HISTORY - -The `export` command was introduced in git-annex version 6.20170925. - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-filter-branch.mdwn b/doc/git-annex-filter-branch.mdwn deleted file mode 100644 --- a/doc/git-annex-filter-branch.mdwn +++ /dev/null @@ -1,151 +0,0 @@ -# NAME - -git-annex filter-branch - filter information from the git-annex branch - -# SYNOPSIS - -git annex filter-branch [...] - -# DESCRIPTION - -This copies selected information from the git-annex branch into a git -commit object, and outputs its hash. The git commit can be transported -to another git repository, and given a branch name such as "foo/git-annex", -and git-annex there will automatically merge that into its git-annex -branch. This allows publishing some information from your git-annex branch, -without publishing the whole thing. - -Other ways to avoid publishing information from a git-annex branch, -or remove information from it include [[git-annex-forget]](1), the -`annex.private` git config, and the `--private` option to -[[git-annex-initremote]](1). Those are much easier to use, but this -provides full control for those who need it. - -With no options, no information at all will be included from the git-annex -branch. Use options to specify what to include. All options can be specified -multiple times. - -When the repository contains information about a private -repository (due to `annex.private` being set, or `git-annex initremote ---private` being used), that private information will be included when -allowed by the options, even though it is not recorded on the git-annex -branch. - -When a repository was created with `git annex initremote --sameas=foo`, -its information will be included when the information for foo is, -and excluded when foo is excluded. - -When a special remote is configured with importtree=yes or exporttree=yes, -normally the git tree corresponding to the repository is included in -the git-annex branch, to make sure it does not get garbage collected -by `git gc`. Those trees are *not* included when filtering the git-annex -branch. Usually this will not cause any problems, but if such a tree does -get garbage collected, it will prevent accessing files on the special -remote, until the next time a tree is imported or exported to it. - -# OPTIONS - -* `path` - - Include information about all keys of annexed files in the path. - -* file matching options - - The [[git-annex-matching-options]](1) - can be used to specify which files in a path to include. - -* `--branch=ref` - - Include information about keys referred of annexed files in the branch - or treeish. - -* `--key=key` - - Include information about a specific key. - -* `--all` - - Include information about all keys. - -* `--include-key-information-for=repo` - - When including information about a key, include information specific to - this repository. The repository can be specified with a uuid or the name - of a remote. This option can be used repeatedly to include several - repositories. - -* `--include-all-key-information` - - Include key information for all repositories, except any excluded with - the `--exclude-key-information-for` option. - -* `--exclude-key-information-for=repo` - - When including information about a key, exclude information specific to - this repository. The repository can be specified with a uuid or the name - of a remote. This option can be used repeatedly to exclude - several repositories. - -* `--include-repo-config-for=repo` - - Include configuration specific to this repository. - The repository can be specified with a uuid or the name of a remote. - - This includes the configuration of special remotes, which may include - embedded credentials, or encryption parameters. It also includes trust - settings, preferred content, etc. It does not include information - about any git-annex keys. This option can be used repeatedly to include - several repositories. - -* `--include-all-repo-config` - - Include the configuration of all repositories, except for any excluded - with the `--exclude-repo-config-for` option. - -* `--exclude-repo-config-for=repo` - - Exclude configuration specific to this repository. - The repository can be specified with a uuid or the name of a remote. - This option can be used repeatedly to exclude several repositories. - -* `--include-global-config` - - Include global configuration, that is not specific to any repository. - - This includes configs stored by [[git-annex-numcopies]](1), - [[git-annex-config]](1), etc. - -# EXAMPLES - -You have a big git-annex repository and are splitting the directory "foo" -out, to make a smaller repository. You want the smaller repo's git-annex -branch to contain all the information about remotes and other configuration, -but only information about keys in that directory. - - git-annex filter-branch foo --include-all-key-information \ - --include-all-repo-config --include-global-config - -That only includes information about the keys that are currently -in the directory "foo", not keys used by old versions of files. -To also include information about the version of the subdir in -tag "1.0", add the option `--branch=1.0:foo` - -Your repository has a special remote "bar", and you want to share information -about which annexed files are stored in it, but without sharing anything -about the configuration of the remote. - - git-annex filter-branch --all --include-all-key-information \ - --include-all-repo-config --exclude-repo-config-for=bar \ - --include-global-config - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-forget]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-find.mdwn b/doc/git-annex-find.mdwn deleted file mode 100644 --- a/doc/git-annex-find.mdwn +++ /dev/null @@ -1,96 +0,0 @@ -# NAME - -git-annex find - lists available files - -# SYNOPSIS - -git annex find `[path ...]` - -# DESCRIPTION - -Outputs a list of annexed files in the specified path. With no path, -finds files in the current directory and its subdirectories. - -# OPTIONS - -* matching options - - The [[git-annex-matching-options]](1) - can be used to specify files to list. - - By default, the find command only lists annexed files whose content is - currently present. Specifying any of the matching options will override - this default behavior. - - To list all annexed files, present or not, specify `--anything`. - - To list annexed files whose content is not present, specify `--not --in=here` - -* `--branch=ref` - - List files in the specified branch or treeish. - -* `--print0` - - Output filenames terminated with nulls, for use with `xargs -0` - -* `--format=value` - - Use custom output formatting. - - The value is a format string, in which '${var}' is expanded to the - value of a variable. To right-justify a variable with whitespace, - use '${var;width}' ; to left-justify a variable, use '${var;-width}'; - to escape unusual characters (including control characters) - in a variable, use '${escaped_var}' - - These variables are available for use in formats: file, key, backend, - bytesize, humansize, keyname, hashdirlower, hashdirmixed, mtime (for - the mtime field of a WORM key). - - Also, '\\n' is a newline, '\\000' is a NULL, etc. - - The default output format is the same as `--format='${file}\\n'`, - except when outputting to a terminal, control characters will be escaped. - -* `--json` - - Output the list of files in JSON format. - - This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* `--batch` - - Enables batch mode, in which a file is read in a line from stdin, - its information displayed, and repeat. - - Note that if the file is not an annexed file, or is not present, - or otherwise doesn't meet the matching options, an empty line - will be output instead. - -* `-z` - - Makes the `--batch` input be delimited by nulls instead of the usual - newlines. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-whereis]](1) - -[[git-annex-findkeys]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-findkeys.mdwn b/doc/git-annex-findkeys.mdwn deleted file mode 100644 --- a/doc/git-annex-findkeys.mdwn +++ /dev/null @@ -1,75 +0,0 @@ -# NAME - -git-annex findkeys - lists available keys - -# SYNOPSIS - -git annex findkeys - -# DESCRIPTION - -Outputs a list of keys known to git-annex. - -# OPTIONS - -* matching options - - The [[git-annex-matching-options]](1) - can be used to specify which keys to list. - - By default, the findkeys command only lists keys whose content is - currently present. Specifying any of the matching options will override - this default behavior and match on all keys that git-annex knows about. - - To list all keys, present or not, specify `--anything`. - - To list keys whose content is not present, specify `--not --in=here` - -* `--print0` - - Output keys terminated with nulls, for use with `xargs -0` - -* `--format=value` - - Use custom output formatting. - - The value is a format string, in which '${var}' is expanded to the - value of a variable. To right-justify a variable with whitespace, - use '${var;width}' ; to left-justify a variable, use '${var;-width}'; - to escape unusual characters (including control characters) - in a variable, use '${escaped_var}' - - These variables are available for use in formats: key, backend, - bytesize, humansize, keyname, hashdirlower, hashdirmixed, mtime (for - the mtime field of a WORM key). - - Also, '\\n' is a newline, '\\000' is a NULL, etc. - - The default output format is the same as `--format='${escapedkey}\\n'` - except when outputting to a terminal, control characters will be escaped. - -* `--json` - - Output the list of keys in JSON format. - - This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-find]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-findref.mdwn b/doc/git-annex-findref.mdwn deleted file mode 100644 --- a/doc/git-annex-findref.mdwn +++ /dev/null @@ -1,27 +0,0 @@ -# NAME - -git-annex findref - lists files in a git ref (deprecated) - -# SYNOPSIS - -git annex findref `[ref]` - -# DESCRIPTION - -This is the same as `git annex find` with the --branch option, and you're -encouraged to use that instead unless you need to support older versions of -git-annex. - -# OPTIONS - -Same as [[git-annex-find]](1) - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-fix.mdwn b/doc/git-annex-fix.mdwn deleted file mode 100644 --- a/doc/git-annex-fix.mdwn +++ /dev/null @@ -1,49 +0,0 @@ -# NAME - -git-annex fix - fix up links to annexed content - -# SYNOPSIS - -git annex fix `[path ...]` - -# DESCRIPTION - -Fixes up symlinks that have become broken to again point to annexed -content. - -This is useful to run manually when you have been moving the symlinks -around, but is done automatically when committing a change with git too. - -Also, adjusts unlocked files to be copies or hard links as -configured by annex.thin. - -# OPTIONS - -* file matching options - - The [[git-annex-matching-options]](1) - can be used to specify files to fix. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-fsck]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-forget.mdwn b/doc/git-annex-forget.mdwn deleted file mode 100644 --- a/doc/git-annex-forget.mdwn +++ /dev/null @@ -1,43 +0,0 @@ -# NAME - -git-annex forget - prune git-annex branch history - -# SYNOPSIS - -git annex forget - -# DESCRIPTION - -Causes the git-annex branch to be rewritten, throwing away historical -data about past locations of files. The resulting branch will use less -space, but `git annex log` will not be able to show where -files used to be located. - -When this rewritten branch is merged into other clones of -the repository, `git-annex` will automatically perform the same rewriting -to their local `git-annex` branches. So the forgetfulness will automatically -propagate out from its starting point until all repositories running -git-annex have forgotten their old history. (You may need to force -git to push the branch to any git repositories not running git-annex.) - -# OPTIONS - -* `--drop-dead` - - Also prune references to repositories that have been marked as dead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-dead]](1) - -[[git-annex-filter-branch]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-fromkey.mdwn b/doc/git-annex-fromkey.mdwn deleted file mode 100644 --- a/doc/git-annex-fromkey.mdwn +++ /dev/null @@ -1,60 +0,0 @@ -# NAME - -git-annex fromkey - adds a file using a specific key - -# SYNOPSIS - -git annex fromkey `[key file ...]` - -# DESCRIPTION - -This plumbing-level command can be used to manually set up a file -in the git repository to link to a specified key. - -Multiple pairs of file and key can be given in a single command line. - -If no key and file pair are specified on the command line, batch input -is used, the same as if the --batch option were specified. - -Normally the key is a git-annex formatted key. However, to make it easier -to use this to add urls, if the key cannot be parsed as a key, and is a -valid url, an URL key is constructed from the url. Note that this does not -register the url as a location of the key; use [[git-annex-registerurl]](1) -to do that. - -# OPTIONS - -* `--force` - - Allow making a file link to a key whose content is not in the local - repository. The key may not be known to git-annex at all. - -* `--batch` - - In batch input mode, lines are read from stdin, and each line - should contain a key and filename, separated by a single space. - -* `-z` - - When in batch mode, the input is delimited by nulls instead of the usual - newlines. - - (Note that for this to be used, you have to explicitly enable batch mode - with `--batch`) - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-fsck.mdwn b/doc/git-annex-fsck.mdwn deleted file mode 100644 --- a/doc/git-annex-fsck.mdwn +++ /dev/null @@ -1,134 +0,0 @@ -# NAME - -git-annex fsck - find and fix problems - -# SYNOPSIS - -git annex fsck `[path ...]` - -# DESCRIPTION - -This command checks annexed files for consistency, and warns about or -fixes any problems found. This is a good complement to `git fsck`. - -The default is to check all annexed files in the current directory and -subdirectories. With parameters, only the specified files are checked. - -The problems fsck finds include files that have gotten corrupted, -files whose content has somehow become lost, files that do not have the -configured number of copies yet made, and keys that can be upgraded to a -better format. - -# OPTIONS - -* `--from=remote` - - Check a remote, rather than the local repository. - - Note that by default, files will be copied from the remote to check - their contents. To avoid this expensive transfer, and only - verify that the remote still has the files that are expected to be on it, - add the `--fast` option. - -* `--fast` - - Avoids expensive checksum calculations (and expensive transfers when - fscking a remote). - -* `--incremental` - - Start a new incremental fsck pass. An incremental fsck can be interrupted - at any time, with eg ctrl-c. - -* `--more` - - Resume the last incremental fsck pass, where it left off. - - Resuming may redundantly check some files that were checked - before. Any files that fsck found problems with before will be re-checked - on resume. Also, checkpoints are made every 1000 files or every 5 minutes - during a fsck, and it resumes from the last checkpoint. - -* `--incremental-schedule=time` - - This makes a new incremental fsck be started only a specified - time period after the last incremental fsck was started. - - The time is in the form "10d" or "300h". - - Maybe you'd like to run a fsck for 5 hours at night, picking up each - night where it left off. You'd like this to continue until all files - have been fscked. And once it's done, you'd like a new fsck pass to start, - but no more often than once a month. Then put this in a nightly cron job: - - git annex fsck --incremental-schedule 30d --time-limit 5h - -* `--numcopies=N` - - Override the normally configured number of copies. - - To verify data integrity only while disregarding required number of copies, - use `--numcopies=1`. - -* `--all` `-A` - - Normally only the files in the currently checked out branch - are fscked. This option causes all versions of all files to be fscked. - - This is the default behavior when running git-annex in a bare repository. - -* `--branch=ref` - - Operate on files in the specified branch or treeish. - -* `--unused` - - Operate on files found by last run of git-annex unused. - -* `--key=keyname` - - Use this option to fsck a specified key. - -* matching options - - The [[git-annex-matching-options]](1) - can be used to control what to fsck. - -* `--jobs=N` `-JN` - - Runs multiple fsck jobs in parallel. For example: `-J4` - - Setting this to "cpus" will run one job per CPU core. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* `--quiet` - - Like all git-annex commands, this option makes only error and warning - messages be displayed. This is particularly useful with fsck, which - normally displays all the files it's checking even when there is no - problem with them. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-repair]](1) - -[[git-annex-expire]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-fuzztest.mdwn b/doc/git-annex-fuzztest.mdwn deleted file mode 100644 --- a/doc/git-annex-fuzztest.mdwn +++ /dev/null @@ -1,27 +0,0 @@ -# NAME - -git-annex fuzztest - generates fuzz test files - -# SYNOPSIS - -git annex fuzztest - -# DESCRIPTION - -Generates random changes to files in the current repository, -for use in testing the assistant. This is dangerous, so it will not -do anything unless --forced. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-get.mdwn b/doc/git-annex-get.mdwn deleted file mode 100644 --- a/doc/git-annex-get.mdwn +++ /dev/null @@ -1,156 +0,0 @@ -# NAME - -git-annex get - make content of annexed files available - -# SYNOPSIS - -git annex get `[path ...]` - -# DESCRIPTION - -Makes the content of annexed files available in this repository. This -will involve copying them from a remote repository, or downloading them, -or transferring them from some kind of key-value store. - -With no parameters, gets all annexed files in the current directory whose -content was not already present. Paths of files or directories to get can -be specified. - -# EXAMPLES - - # evince foo.pdf - error: Unable to open document foo.pdf: No such file or directory - # ls foo.pdf - foo.pdf@ - # git annex get foo.pdf - get foo.pdf (from origin..) ok - # evince foo.pdf - -# OPTIONS - -* `--auto` - - Rather than getting all the specified files, get only those that don't yet - have the desired number of copies, or that are preferred content of the - repository. See [[git-annex-preferred-content]](1) - -* `--from=remote` - - Normally git-annex will choose which remotes to get the content - from, preferring remotes with lower costs. Use this option to specify - which remote to use. - - Any files that are not available on the remote will be silently skipped. - -* `--jobs=N` `-JN` - - Enables parallel download 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 files can be downloaded from multiple remotes, enabling parallel - downloads will split the load between the remotes. For example, if - the files are available on remotes A and B, then one file will be - downloaded from A, and another file will be downloaded from B in - parallel. (Remotes with lower costs are still preferred over higher cost - remotes.) - -* matching options - - The [[git-annex-matching-options]](1) - can be used to control what to get. - -* `--incomplete` - - Resume any incomplete downloads of files that were started and - interrupted at some point previously. Useful to pick up where you left - off ... when you don't quite remember where that was. - - These incomplete files are the same ones that are - listed as unused temp files by [[git-annex-unused]](1). - - Note that the git-annex key will be displayed when downloading, - as git-annex does not know the associated file, and the associated file - may not even be in the current git working directory. - -* `--all` `-A` - - Rather than specifying a filename or path to get, this option can be - used to get all available versions of all files. - - This is the default behavior when running git-annex in a bare repository. - -* `--branch=ref` - - Operate on files in the specified branch or treeish. - -* `--unused` - - Operate on files found by last run of git-annex unused. - -* `--failed` - - Operate on files that have recently failed to be transferred. - - Not to be confused with `--incomplete` which resumes only downloads - that managed to transfer part of the content of a file. - -* `--key=keyname` - - Use this option to get a specified key. - -* `--batch` - - Enables batch mode, in which lines containing names of files to get - are read from stdin. - - As each specified file is processed, the usual progress output is - displayed. If the specified file's content is already present, - or it does not match specified matching options, or - it is not an annexed file, a blank line is output in response instead. - - Since the usual output while getting a file is verbose and not - machine-parseable, you may want to use --json in combination with - --batch. - -* `--batch-keys` - - This is like `--batch` but the lines read from stdin are parsed as keys. - -* `-z` - - Makes batch input be delimited by nulls instead of the usual - newlines. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-progress` - - Include progress objects in JSON output. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-drop]](1) - -[[git-annex-copy]](1) - -[[git-annex-move]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-group.mdwn b/doc/git-annex-group.mdwn deleted file mode 100644 --- a/doc/git-annex-group.mdwn +++ /dev/null @@ -1,39 +0,0 @@ -# NAME - -git-annex group - add a repository to a group - -# SYNOPSIS - -git annex group `repository [groupname]` - -# DESCRIPTION - -Adds a repository to a group, such as "archival", "enduser", or "transfer". -The groupname must be a single word. - -Omit the groupname to show the current groups that a repository is in. - -There are some standard groups that have different default preferred content -settings. See - -A repository can be in multiple groups at the same time. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-ungroup]](1) - -[[git-annex-preferred-content]](1) - -[[git-annex-wanted]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-groupwanted.mdwn b/doc/git-annex-groupwanted.mdwn deleted file mode 100644 --- a/doc/git-annex-groupwanted.mdwn +++ /dev/null @@ -1,46 +0,0 @@ -# NAME - -git-annex groupwanted - get or set groupwanted expression - -# SYNOPSIS - -git annex groupwanted `groupname [expression]` - -# DESCRIPTION - -Sets or displays the groupwanted expression. This will be used by -repositories that are in the group, and that have their preferred -content expression set to "groupwanted". - -For example, to configure a group named redundantarchive, and -make repositories in the group want to contain 3 copies of every file: - - git annex groupwanted redundantarchive "not (copies=redundantarchive:3)" - for repo in foo bar baz; do - git annex group $repo redundantarchive - git annex wanted $repo groupwanted - done - -Note that there must be exactly one groupwanted expression configured -amoung all the groups that a repository is in; if there's more than one, -none of them will be used. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-group]](1) - -[[git-annex-wanted]](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-import.mdwn b/doc/git-annex-import.mdwn deleted file mode 100644 --- a/doc/git-annex-import.mdwn +++ /dev/null @@ -1,241 +0,0 @@ -# NAME - -git-annex import - import files from a special remote - -# SYNOPSIS - -git annex import --from remote branch[:subdir] | `[path ...]` - -# DESCRIPTION - -This command is a way to import a tree of files from elsewhere into your -git-annex repository. It can import files from a git-annex special remote, -or from a directory. - -# IMPORTING FROM A SPECIAL REMOTE - -Importing from a special remote first downloads or hashes all new content -from it, and then constructs a git commit that reflects files that have -changed on the special remote since the last time git-annex looked at it. -Merging that commit into your repository will update it to reflect changes -made on the special remote. - -This way, something can be using the special remote for file storage, -adding files, modifying files, and deleting files, and you can track those -changes using git-annex. - -You can combine using `git annex import` to fetch changes from a special -remote with `git annex export` to send your local changes to the special -remote. - -You can only import from special remotes that were configured with -`importtree=yes` when set up with [[git-annex-initremote]](1). Only some -kinds of special remotes will let you configure them this way. A perhaps -non-exhaustive list is the directory, s3, and adb special remotes. - -To import from a special remote, you must specify the name of a branch. -A corresponding remote tracking branch will be updated by `git annex import`. -After that point, it's the same as if you had run a `git fetch` -from a regular git remote; you can merge the changes into your -currently checked out branch. - -For example: - - git annex import master --from myremote - git annex merge --allow-unrelated-histories myremote/master - -You could just as well use `git merge --allow-unrelated-histories myremote/master` -as the second step, but using `git-annex merge` avoids a couple of gotchas. -When using adjusted branches, it adjusts the branch before merging from it. - -The --allow-unrelated-histories option is needed for at least the first -merge of an imported remote tracking branch, since the branch's history is -not connected. Think of this as the remote being a separate git repository -with its own files. If you first `git annex export` files to a remote, and -then `git annex import` from it, you won't need that option. - -You can import into a subdirectory, using the "branch:subdir" syntax. For -example, if "camera" is a special remote that accesses a camera, and you -want to import those into the photos directory, rather than to the root of -your repository: - - git annex import master:photos --from camera - git merge camera/master - -The `git annex sync --content` command (and the git-annex assistant) -can also be used to import from a special remote. -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 - -Any files that are gitignored will not be included in the import, -but will be left on the remote. - -When the special remote has a preferred content expression set by -[[git-annex-wanted]](1), it will be honored when importing from it. -Files that are not preferred content of the remote will not be -imported from it, but will be left on the remote. - -However, preferred content expressions that relate to the key -can't be matched when importing, because the content of the file is not -known. Importing will fail when such a preferred content expression is -set. This includes expressions containing "copies=", "metadata=", and other -things that depend on the key. Preferred content expressions containing -"include=", "exclude=" "smallerthan=", "largerthan=" will work. - -Things in the expression like "include=" match relative to the top of -the tree of files on the remote, even when importing into a subdirectory. - -# OPTIONS FOR IMPORTING FROM A SPECIAL REMOTE - -* `--content`, `--no-content` - - Controls whether annexed content is downloaded from the special remote. - - The default is to download content into the git-annex repository. - - With --no-content, git-annex keys are generated from information - provided by the special remote, without downloading it. Commands like - `git-annex get` can later be used to download files, as desired. - The --no-content option is not supported by all special remotes. - -# IMPORTING FROM A DIRECTORY - -When run with a path, `git annex import` **moves** files from somewhere outside -the git working copy, and adds them to the annex. In contrast to importing -from a special directory remote, imported files are **deleted from the given -path**. - -This is a legacy interface. It is still supported, but please consider -switching to importing from a directory special remote instead, using the -interface documented above. - -Individual files to import can be specified. If a directory is specified, -the entire directory is imported. Please note that the following instruction -will **delete all files from the source directory**. - - git annex import /media/camera/DCIM/* - -When importing files, there's a possibility of importing a duplicate -of a file that is already known to git-annex -- its content is either -present in the local repository already, or git-annex knows of another -repository that contains it, or it was present in the annex before but has -been removed now. - -By default, importing a duplicate of a known file will result in -a new filename being added to the repository, so the duplicate file -is present in the repository twice. (With all checksumming backends, -including the default SHA256E, only one copy of the data will be stored.) - -Several options can be used to adjust handling of duplicate files, see -`--duplicate`, `--deduplicate`, `--skip-duplicates`, `--clean-duplicates`, -and `--reinject-duplicates` documentation below. - -symbolic links in the directory being imported are skipped to avoid -accidentially importing things outside the directory that import was ran -on. The directory that import is run on can, however inself be a symbolic -link, and that symbolic link will be followed. - -# OPTIONS FOR IMPORTING FROM A DIRECTORY - -* `--duplicate` - - Do not delete files from the import location. - - Running with this option repeatedly can import the same files into - different git repositories, or branches, or different locations in a git - repository. - -* `--deduplicate` - - Only import files that are not duplicates; - duplicate files will be deleted from the import location. - -* `--skip-duplicates` - - Only import files that are not duplicates. Avoids deleting any - files from the import location. - -* `--clean-duplicates` - - Does not import any files, but any files found in the import location - that are duplicates are deleted. - -* `--reinject-duplicates` - - Imports files that are not duplicates. Files that are duplicates have - their content reinjected into the annex (similar to - [[git-annex-reinject]](1)). - -* `--force` - - Allow existing files to be overwritten by newly imported files. - - Also, causes .gitignore to not take effect when adding files. - -* file matching options - - Many of the [[git-annex-matching-options]](1) - can be used to specify files to import. - - git annex import /dir --include='*.png' - -# COMMON OPTIONS - -* `--jobs=N` `-JN` - - Imports multiple files in parallel. This may be faster. - For example: `-J4` - - Setting this to "cpus" will run one job per CPU core. - -* `--backend` - - Specifies which key-value backend to use for the imported files. - -* `--no-check-gitignore` - - Add gitignored files. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-progress` - - Include progress objects in JSON output. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# CAVEATS - -Note that using `--deduplicate` or `--clean-duplicates` with the WORM -backend does not look at file content, but filename and mtime. - -If annex.largefiles is configured, and does not match a file, `git annex -import` will add the non-large file directly to the git repository, -instead of to the annex. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-add]](1) - -[[git-annex-export]](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-importfeed.mdwn b/doc/git-annex-importfeed.mdwn deleted file mode 100644 --- a/doc/git-annex-importfeed.mdwn +++ /dev/null @@ -1,141 +0,0 @@ -# NAME - -git-annex importfeed - import files from podcast feeds - -# SYNOPSIS - -git annex importfeed `[url ...]` - -# DESCRIPTION - -Imports the contents of podcasts and other feeds. Only downloads files whose -content has not already been added to the repository before, so you can -delete, rename, etc the resulting files and repeated runs won't duplicate -them. - -When `yt-dlp` is installed, it can be used to download links in the feed. -This allows importing e.g., YouTube playlists. -(However, this is disabled by default as it can be a security risk. -See the documentation of annex.security.allowed-ip-addresses -in [[git-annex]](1) for details.) - -To make the import process add metadata to the imported files from the feed, -`git config annex.genmetadata true` - -By default, the downloaded files are put in a directory with the title -of the feed, and files are named based on the title of the item in the -feed. This can be changed using the --template option. - -Existing files are not overwritten by this command. If "some feed/foo.mp3" -already exists, it will instead write to "some feed/2\_foo.mp3" -(or 3, 4, etc). Sometimes a feed will change an item's url, -resulting in the new url being downloaded to such a filename. - -# OPTIONS - -* `--force` - - Force downloading items it's seen before. - -* `--relaxed`, `--fast`, `--raw` - - These options behave the same as when using [[git-annex-addurl]](1). - -* `--fast` - - Avoid immediately downloading urls. The url is still checked - (via HEAD) to verify that it exists, and to get its size if possible. - -* `--relaxed` - - Don't immediately download urls, and avoid storing the size of the - url's content. This makes git-annex accept whatever content is there - at a future point. - -* `--raw` - - Prevent special handling of urls by yt-dlp, bittorrent, and other - special remotes. This will for example, make importfeed - download a .torrent file and not the contents it points to. - -* `--no-raw` - - Require content pointed to by the url to be downloaded using yt-dlp - or a special remote, rather than the raw content of the url. if that - cannot be done, the import will fail, and the next import of the feed - will retry. - -* `--template` - - Controls where the files are stored. - - The default template is '${feedtitle}/${itemtitle}${extension}' - - The available variables in the template include these that - are information about the feed: feedtitle, feedauthor, feedurl - - And these that are information about individual items in the feed: - itemtitle, itemauthor, itemsummary, itemdescription, itemrights, - itemid. - - Also, title is itemtitle but falls back to feedtitle if the item has no - title, and author is itemauthor but falls back to feedauthor. - - (All of the above are also added as metadata when annex.genmetadata is - set.) - - The extension variable is the extension of the file in the feed, - or sometimes ".m" if no extension can be determined. - - The template also has some variables for when an item was published. - - itempubyear (YYYY), itempubmonth (MM), itempubday (DD), itempubhour (HH), - itempubminute (MM), itempubsecond (SS), - itempubdate (YYYY-MM-DD or if the feed's date cannot be parsed, the raw - value from the feed). - - (These use the UTC time zone, not the local time zone.) - -* `--no-check-gitignore` - - By default, gitignores are honored and it will refuse to download an - url to a file that would be ignored. This makes such files be added - despite any ignores. - -* `--jobs=N` `-JN` - - Runs multiple downloads parallel. For example: `-J4` - - Setting this to "cpus" will run one job per CPU core. - -* `--backend` - - Specifies which key-value backend to use. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-progress` - - Include progress objects in JSON output. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-addurl]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-indirect.mdwn b/doc/git-annex-indirect.mdwn deleted file mode 100644 --- a/doc/git-annex-indirect.mdwn +++ /dev/null @@ -1,27 +0,0 @@ -# NAME - -git-annex indirect - switch repository to indirect mode (deprecated) - -# SYNOPSIS - -git annex indirect - -# DESCRIPTION - -This command was used to switch a repository back from direct mode -indirect mode. - -Now git-annex automatically converts direct mode repositories to v7 -with adjusted unlocked branches, so this command does nothing. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-direct]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-info.mdwn b/doc/git-annex-info.mdwn deleted file mode 100644 --- a/doc/git-annex-info.mdwn +++ /dev/null @@ -1,76 +0,0 @@ -# NAME - -git-annex info - information about an item or the repository - -# SYNOPSIS - -git annex info `[directory|file|treeish|remote|description|uuid ...]` - -# DESCRIPTION - -Displays statistics and other information for the specified item, -which can be a directory, or a file, or a treeish, or a remote, -or the description or uuid of a repository. - -When no item is specified, displays statistics and information -for the local repository and all annexed content. - -# OPTIONS - -* `--fast` - - Only show the data that can be gathered quickly. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* `--bytes` - - Show file sizes in bytes, disabling the default nicer units. - -* `--batch` - - Enable batch mode, in which a line containing an item is read from stdin, - the information about it is output to stdout, and repeat. - -* `-z` - - Makes the `--batch` input be delimited by nulls instead of the usual - newlines. - -* `--autoenable` - - Display a list of special remotes that have been configured to - autoenable. - -* matching options - - The [[git-annex-matching-options]](1) can be used to select what - to include in the statistics. - -* Also the [[git-annex-common-options]](1) can be used. - -# EXAMPLES - -Suppose you want to run "git annex get .", but -would first like to see how much disk space that will use. -Then run: - - git annex info --fast . --not --in here - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-init.mdwn b/doc/git-annex-init.mdwn deleted file mode 100644 --- a/doc/git-annex-init.mdwn +++ /dev/null @@ -1,86 +0,0 @@ -# NAME - -git-annex init - initialize git-annex - -# SYNOPSIS - -git annex init `[description]` - -# DESCRIPTION - -Until a repository (or one of its remotes) has been initialized, -git-annex will refuse to operate on it, to avoid accidentally -using it in a repository that was not intended to have an annex. - -It's useful, but not mandatory, to initialize each new clone -of a repository with its own description. If you don't provide one, -one will be generated using the username, hostname and the path. - -If any special remotes were configured with autoenable=true, -this will also attempt to enable them. See [[git-annex-initremote]](1). -To prevent that, re-enable a remote with "autoenable=false", or -mark it as dead (see [[git-annex-dead]](1)). - -This command is entirely safe, although usually pointless, to run inside an -already initialized git-annex repository. - -A top-level `.noannex` file will prevent git-annex init from being used -in a repository. This is useful for repositories that have a policy -reason not to use git-annex. The content of the file will be displayed -to the user who tries to run git-annex init. - -# EXAMPLES - - # git annex add foo - git-annex: First run: git-annex init - # git annex init - init ok - # git annex add foo - add foo ok - -# OPTIONS - -* `--version=N` - - Force the repository to be initialized using a different annex.version - than the current default. - - When the version given is not supported, but can be automatically - upgraded to a newer version, it will use the newer version instead. - -* `--autoenable` - - Only enable any special remotes that were configured with - autoenable=true, do not otherwise initialize anything. - -* `--no-autoenable` - - Do not enable special remotes that were configured with autoenable=true. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-describe]](1) - -[[git-annex-reinit]](1) - -git-init(1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-initremote.mdwn b/doc/git-annex-initremote.mdwn deleted file mode 100644 --- a/doc/git-annex-initremote.mdwn +++ /dev/null @@ -1,148 +0,0 @@ -# NAME - -git-annex initremote - creates a special (non-git) remote - -# SYNOPSIS - -git annex initremote `name type=value [param=value ...]` - -# DESCRIPTION - -Creates a new special remote, and adds it to `.git/config`. - -Example Amazon S3 remote: - - git annex initremote mys3 type=S3 encryption=hybrid keyid=me@example.com datacenter=EU - -Many different types of special remotes are supported by git-annex. -For a list and details, see - -The remote's configuration is specified by the parameters passed -to this command. Different types of special remotes need different -configuration values, so consult the documentation of a special remote for -details. The command will prompt for any required parameters you leave out; -you can also pass --whatelse to see additional parameters. - -A few parameters that are supported by all special remotes are documented in -the next section below. - -Once a special remote has been initialized once with this command, -other clones of the repository can also be set up to access it using -`git annex enableremote`. - -The name you provide for the remote can't be one that's been used for any -other special remote before, because `git-annex enableremote` uses the name -to identify which special remote to enable. If some old special remote -that's no longer used has taken the name you want to reuse, you might -want to use `git annex renameremote`. - -# OPTIONS - -* `--whatelse` / `-w` - - Describe additional configuration parameters that you could specify. - - For example, if you know you want a S3 remote, but forget how to - configure it: - - git annex initremote mys3 type=S3 --whatelse - - For a machine-readable list of the parameters, use this with --json. - -* `--fast` - - When initializing a remote that uses encryption, a cryptographic key is - created. This requires sufficient entropy. If initremote seems to hang - or take a long time while generating the key, you may want to Ctrl-c it - and re-run with `--fast`, which causes it to use a lower-quality source of - randomness. (Ie, /dev/urandom instead of /dev/random) - -* `--sameas=remote` - - Use this when the new special remote uses the same underlying storage - as some other remote. This will result in the new special remote having - the same uuid as the specified remote, and either can be used to access - the same content. - - The `remote` can be the name of a git remote, or the description - or uuid of any git-annex repository. - - When using this option, the new remote inherits the encryption settings - of the existing remote, so you should not specify any encryption - parameters. No other configuration is inherited from the existing remote. - - This will only work if both remotes use the underlying storage in - compatible ways. See this page for information about known - compatabilities. - - -* `--private` - - Avoid recording information about the special remote in the git-annex - branch. The special remote will only be usable from the repository where - it was created. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# COMMON CONFIGURATION PARAMETERS - -* `encryption` - - Almost all special remotes support encryption. You will need to specify - what encryption, if any, to use. - - If you do not want any encryption, use `encryption=none` - - To encrypt to a GPG key, use `encryption=hybrid keyid=$keyid ...` - and fill in the GPG key id (or an email address associated with a GPG key). - - For details about this and other encrpytion settings, see - - or --whatelse - -* `autoenable` - - To avoid `git annex enableremote` needing to be run, - you can pass "autoenable=true". Then when git-annex is run in a new clone, - it will attempt to enable the special remote. Of course, this works best - when the special remote does not need anything special to be done to get - it enabled. - -* `cost` - - Specify this to override the default cost of the special remote. - This configuration can be overridden by the local git config, - eg remote.name.annex-cost. - -* `uuid` - - Normally, git-annex initremote generates a new UUID for the new special - remote. If you want to, you can specify a UUID for it to use, by passing a - uuid=whatever parameter. This can be useful in some unusual situations. - But if in doubt, don't do this. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-enableremote]](1) - -[[git-annex-configremote]](1) - -[[git-annex-renameremote]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-inprogress.mdwn b/doc/git-annex-inprogress.mdwn deleted file mode 100644 --- a/doc/git-annex-inprogress.mdwn +++ /dev/null @@ -1,72 +0,0 @@ -# NAME - -git-annex inprogress - access files while they're being downloaded - -# SYNOPSIS - -git annex inprogress `[path ...]` - -# DESCRIPTION - -This command allows accessing the content of an annexed file while -it is still being downloaded. It outputs to standard output the -name of the temporary file that is being used to download the specified -annexed file. - -Nothing will be output when the download is from an encrypted or chunked -special remote. - -This can sometimes be used to stream a file before it's been fully -downloaded, for example: - - git annex get video.mpeg & - vlc $(git annex inprogress video.mpeg) - -Of course if the file is downloading too slowly, the media player will -reach the end too soon and not show the whole thing. And of course, only -some file formats can be usefully streamed in this way. - -# OPTIONS - -* `[path ..]` - - The files or directories whose partially downloaded content you want to - access. - - Note that, when no path is specified, it defaults to all files in the - current working directory, and subdirectories, which can take a while to - traverse. It's most efficient to specify a the file you are interested - in, or to use `--all` - -* `--all` `-A` - - Rather than specifying a filename or path, this option can be - used to access all files that are currently being downloaded. - -* `--key=keyname` - - Access the file that is currently being downloaded for the specified key. - -* file matching options - - The [[git-annex-matching-options]](1) - can be used to specify files to access. - -* Also the [[git-annex-common-options]](1) can be used. - -# EXIT STATUS - -If any of the requested items are not currently being downloaded, -the exit status will be 1. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-get]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-list.mdwn b/doc/git-annex-list.mdwn deleted file mode 100644 --- a/doc/git-annex-list.mdwn +++ /dev/null @@ -1,40 +0,0 @@ -# NAME - -git-annex list - show which remotes contain files - -# SYNOPSIS - -git annex list `[path ...]` - -# DESCRIPTION - -Displays a table of remotes that contain the contents of the specified -files. This is similar to `git annex whereis` but a more compact display. - -# OPTIONS - -* `--allrepos` - - Only configured remotes are shown by default; this option - adds all known repositories to the list. - -* file matching options - - The [[git-annex-matching-options]](1) - can be used to specify files to list. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-find]](1) - -[[git-annex-whereis]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-lock.mdwn b/doc/git-annex-lock.mdwn deleted file mode 100644 --- a/doc/git-annex-lock.mdwn +++ /dev/null @@ -1,50 +0,0 @@ -# NAME - -git-annex lock - lock files to prevent modification - -# SYNOPSIS - -git annex lock `[path ...]` - -# DESCRIPTION - -Lock the specified annexed files, to prevent them from being modified. -When no files are specified, all annexed files in the current directory are -locked. - -Locking a file changes how it is stored in the git repository (from a -pointer file to a symlink), so this command will make a change that you -can commit. - -# OPTIONS - -* file matching options - - The [[git-annex-matching-options]](1) - can be used to specify files to lock. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-add]](1) - -[[git-annex-unlock]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-log.mdwn b/doc/git-annex-log.mdwn deleted file mode 100644 --- a/doc/git-annex-log.mdwn +++ /dev/null @@ -1,75 +0,0 @@ -# NAME - -git-annex log - shows location log - -# SYNOPSIS - -git annex log `[path ...]` - -# DESCRIPTION - -Displays the location log for the specified file or files, showing each -repository they were added to ("+") and removed from ("-"). Note that the -location log is for the particular file contents currently at these paths, -not for any different content that was there in earlier commits. - -This displays information from the history of the git-annex branch. Several -things can prevent that information being available to display. When -[[git-annex-dead]] and [[git-annex-forget]] are used, old historical -data gets cleared from the branch. When annex.private or -remote.name.annex-private is configured, git-annex does not write -information to the branch at all. And when annex.alwayscommit is set to -false, information may not have been committed to the branch yet. - -# OPTIONS - -* `--since=date`, `--after=date`, `--until=date`, `--before=date`, `--max-count=N` - - These options are passed through to `git log`, and can be used to limit - how far back to search for location log changes. - - For example: `--since "1 month ago"` - -* `--raw-date` - - Rather than the normal display of a date in the local time zone, - displays seconds since the unix epoch. - -* `--gource` - - Generates output suitable for the `gource` visualization program. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* matching options - - The [[git-annex-matching-options]](1) - can be used to control what to act on. - -* `--all` `-A` - - Shows location log changes to all content, with the most recent changes first. - In this mode, the names of files are not available and keys are displayed - instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-forget]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-lookupkey.mdwn b/doc/git-annex-lookupkey.mdwn deleted file mode 100644 --- a/doc/git-annex-lookupkey.mdwn +++ /dev/null @@ -1,41 +0,0 @@ -# NAME - -git-annex lookupkey - looks up key used for file - -# SYNOPSIS - -git annex lookupkey `[file ...]` - -# DESCRIPTION - -This plumbing-level command looks up the key used for a file in the -index. The key is output to stdout. If there is no key (because -the file is not present in the index, or is not a git-annex managed file), -nothing is output, and it exits nonzero. - -# OPTIONS - -* `--batch` - - Enable batch mode, in which a line containing the filename is read from - stdin, the key is output to stdout (with a trailing newline), and repeat. - - Note that if there is no key corresponding to the file, an empty line is - output to stdout instead. - -* `-z` - - Makes the `--batch` input be delimited by nulls instead of the usual - newlines. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-map.mdwn b/doc/git-annex-map.mdwn deleted file mode 100644 --- a/doc/git-annex-map.mdwn +++ /dev/null @@ -1,52 +0,0 @@ -# NAME - -git-annex map - generate map of repositories - -# SYNOPSIS - -git annex map - -# DESCRIPTION - -Helps you keep track of your repositories, and the connections between them, -by going out and looking at all the ones it can get to, and generating a -Graphviz file displaying it all. If the `xdot` or `dot` command is available, -it is used to display the file to your screen. - -This command only connects to hosts that the host it's run on can -directly connect to. It does not try to tunnel through intermediate hosts. -So it might not show all connections between the repositories in the network - -Also, if connecting to a host requires a password, you might have to enter -it several times as the map is being built. - -Note that this subcommand can be used to graph any git repository; it -is not limited to git-annex repositories. - -# LEGEND - -Ovals are repositories. White is regular, green is trusted, red is -untrusted, and grey is dead. - -Arrows between repositories are connections via git remotes. - -Light blue boxes are hosts that were mapped, and contain the repositories -on that host. - -# OPTIONS - -* `--fast` - - Don't display the generated Graphviz file, but save it for later use. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-matchexpression.mdwn b/doc/git-annex-matchexpression.mdwn deleted file mode 100644 --- a/doc/git-annex-matchexpression.mdwn +++ /dev/null @@ -1,75 +0,0 @@ -# NAME - -git-annex matchexpression - checks if an expression matches - -# SYNOPSIS - -git annex matchexpression `expression [data]` - -# DESCRIPTION - -This plumbing-level command is given a preferred content expression, -and some data, and checks if the expression matches the data. It exits 0 if -it matches, and 1 if not. If not enough data was provided, it displays an -error and exits with special code 42. - -For example, this will exit 0: - - git annex matchexpression "include=*.png and largerthan=1mb" --file=foo.png --size=10mb - -# OPTIONS - -* `--file=` - - Provide the filename to match against. Note that the file does not have - to actually exist on disk. - -* `--size=` - - Tell what the size of the file is. The size can be specified with any - commonly used units, for example, "0.5 gb" or "100 KiloBytes". - -* `--key=` - - Tell what key is being matched against. This is needed for - matching expressions like "copies=N" and "metadata=tag=foo" and - "present", which all need to look up the information on file for a key. - - Many keys have a known size, and so --size is not needed when specifying - such a key. - -* `--largefiles` - - Parse the expression as an annex.largefiles expression, rather than a - preferred content expression. - -* `--mimetype=` - - Tell what the mime type of the file is. Only needed when using - --largefiles with a mimetype= expression. - -* `--mimeencoding=` - - Tell what the mime encoding of the file is. Only needed when using - --largefiles with a mimeencoding= expression. - -* `--explain` - - Display explanation of what parts of the preferred content expression - match, and which parts don't match. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-preferred-content]](1) - -[[git-annex-matching-expression]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-matching-options.mdwn b/doc/git-annex-matching-options.mdwn deleted file mode 100644 --- a/doc/git-annex-matching-options.mdwn +++ /dev/null @@ -1,293 +0,0 @@ -# NAME - -git-annex-matching-options - specifying what to act on - -# DESCRIPTION - -Many git-annex commands support using these options to specify which -files they act on. Some of these options can also be used by commands to -specify which keys they act on. - -Arbitrarily complicated expressions can be built using these options. -For example: - - --include='*.mp3' --and -( --in=usbdrive --or --in=archive -) - -The above example makes git-annex work on only mp3 files that are present -in either of two repositories. - -# OPTIONS - -* `--exclude=glob` - - Skips files matching the glob pattern. The glob is matched relative to - the current directory. For example: - - git annex get --exclude='*.mp3' --exclude='subdir/*' - - Note that this will not match anything when using --all or --unused. - -* `--include=glob` - - Skips files not matching the glob pattern. (Same as `--not --exclude`.) - For example, to include only mp3 and ogg files: - - git annex get --include='*.mp3' --or --include='*.ogg' - - Note that this will not skip anything when using --all or --unused. - -* `--excludesamecontent=glob` - - Skips a file when there is another file with the same content, - whose name matches the glob. The glob is matched relative to the current - directory. - - For example, to drop files in the archive directory, but not when the same - content is used by a file in the work directory: - - git annex drop archive/ --excludesamecontent='work/*' - -* `--includesamecontent=glob` - - Skips files when there is no other file with the same content - whose name matches the glob. (Same as `--not --includesamecontent`) - - For example, if you have inbox and outbox directories, and want to find - anything in the inbox that has the same content as something in the outbox: - - git annex find inbox --includesamecontent='outbox/*' - -* `--in=repository` - - Matches only when git-annex believes that the content is present in a - repository. Note that it does not check the repository to verify - that it still has the content. - - The repository should be specified using the name of a configured remote, - or the UUID or description of a repository. For the current repository, - use `--in=here` - -* `--in=repository@{date}` - - Matches only when the content was present in a repository on the given - date. - - The date is specified in the same syntax documented in - gitrevisions(7). Note that this uses the reflog, so dates far in the - past cannot be queried. - - For example, you might need to run `git annex drop .` to temporarily - free up disk space. The next day, you can get back the files you dropped - using `git annex get . --in=here@{yesterday}` - -* `--copies=number` - - Matches only when git-annex believes there are the specified number - of copies, or more. Note that it does not check remotes to verify that - the copies still exist. - -* `--copies=trustlevel:number` - - Matches only when git-annex believes there are the specified number of - copies, on remotes with the specified trust level. For example, - `--copies=trusted:2` - - To match any trust level at or higher than a given level, - use 'trustlevel+'. For example, `--copies=semitrusted+:2` - -* `--copies=groupname:number` - - Matches only when git-annex believes there are the specified number of - copies, on remotes in the specified group. For example, - `--copies=archive:2` - -* `--lackingcopies=number` - - Matches only when git-annex beleives that the specified number or - more additional copies to be made in order to satisfy numcopies - settings. - -* `--approxlackingcopies=number` - - Like lackingcopies, but does not look at .gitattributes annex.numcopies - settings. This makes it significantly faster. - -* `--inbackend=name` - - Matches only when content is stored using the specified key-value - backend. - -* `--securehash` - - Matches only when content is hashed using a cryptographically - secure function. - -* `--inallgroup=groupname` - - Matches only when git-annex believes content is present in - all repositories in the specified group. - -* `--onlyingroup=groupname` - - Matches only when git-annex believes content is present in at least one - repository that is in the specified group, and is not present in any - repositories that are not in the specified group. - -* `--smallerthan=size` -* `--largerthan=size` - - Matches only when the content is is smaller than, or larger than the - specified size. - - The size can be specified with any commonly used units, for example, - "0.5 gb" or "100 KiloBytes" - -* `--metadata field=glob` - - Matches only when there is a metadata field attached with a value that - matches the glob. The values of metadata fields are matched case - insensitively. - -* `--metadata fieldvalue` -* `--metadata field<=value` / `--metadata field>=value` - - Matches only when there is a metadata field attached with a value - that is less then or greater than the specified value, respectively. - - When both values are numbers, the comparison is done numerically. - When one value is not a number, the values are instead compared - lexicographically. - - (Note that you will need to quote the second parameter to avoid - the shell doing redirection.) - -* `--want-get` - - Matches only when the preferred content settings for the local repository - make it want to get content. Note that this will match even when - the content is already present, unless limited with e.g., `--not --in=here` - -* `--want-drop` - - Matches only when the preferred content settings for the local repository - make it want to drop content. Note that this will match even when - the content is not present, unless limited with e.g., `--not --in=here` - - Things that this matches will not necessarily be dropped by - `git-annex drop --auto`. This does not check that there are enough copies - to drop. Also the same content may be used by a file that is not wanted - to be dropped. - -* `--want-get-by=repository` - - Matches only when the preferred content settings for the specified - repository make it want to get content. Note that this will match even when - the content is already present in that repository, unless limited with e.g., - `--not --in=repository` - - The repository should be specified using the name of a configured remote, - or the UUID or description of a repository. `--want-get-by=here` - is the same as `--want-get`. - -* `--want-drop-by=repository` - - Matches only when the preferred content settings for the specificed - repository make it want to drop content. Note that this will match - even when the content is not present, unless limited with e.g., - `--not --in=repository` - - The repository should be specified using the name of a configured remote, - or the UUID or description of a repository. `--want-drop-by=here` - is the same as `--want-drop`. - -* `--accessedwithin=interval` - - Matches when the content was accessed recently, within the specified time - interval. - - The interval can be in the form "5m" or "1h" or "2d" or "1y", or a - combination such as "1h5m". - - So for example, `--accessedwithin=1d` matches when the content was - accessed within the past day. - - If the OS or filesystem does not support access times, this will not - match anything. - -* `--unlocked` - - Matches annexed files that are unlocked. - -* `--locked` - - Matches annexed files that are locked. - -* `--mimetype=glob` - - Looks up the MIME type of a file, and checks if the glob matches it. - - For example, `--mimetype="text/*"` will match many varieties of text files, - including "text/plain", but also "text/x-shellscript", "text/x-makefile", - etc. - - The MIME types are the same that are displayed by running `file --mime-type` - - If the file's annexed content is not present, the file will not match. - - This is only available to use when git-annex was built with the - MagicMime build flag. - -* `--mimeencoding=glob` - - Looks up the MIME encoding of a file, and checks if the glob matches it. - - For example, `--mimeencoding=binary` will match many kinds of binary - files. - - The MIME encodings are the same that are displayed by running `file --mime-encoding` - - If the file's annexed content is not present, the file will not match. - - This is only available to use when git-annex was built with the - MagicMime build flag. - -* `--anything` - - Always matches. One way this can be useful is `git-annex find --anything` - will list all annexed files, whether their content is present or not. - -* `--nothing` - - Never matches. (Same as `--not --anything`) - -* `--not` - - Inverts the next matching option. For example, to match - when there are less than 3 copies, use `--not --copies=3` - -* `--and` - - Requires that both the previous and the next matching option matches. - The default. - -* `--or` - - Requires that either the previous, or the next matching option matches. - -* `-(` - - Opens a group of matching options. - -* `-)` - - Closes a group of matching options. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-merge.mdwn b/doc/git-annex-merge.mdwn deleted file mode 100644 --- a/doc/git-annex-merge.mdwn +++ /dev/null @@ -1,56 +0,0 @@ -# NAME - -git-annex merge - merge changes from remotes - -# SYNOPSIS - -git annex merge [branch] - -# DESCRIPTION - -When run without any parameters, this performs the same merging (and merge -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 `git-annex pull` command. This is especially useful on -an adjusted branch, because it applies the same adjustment to the -branch before merging it. - -When annex.resolvemerge is set to false, merge conflict resolution -will not be done. - -# OPTIONS - -* `--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. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* 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-adjust]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-metadata.mdwn b/doc/git-annex-metadata.mdwn deleted file mode 100644 --- a/doc/git-annex-metadata.mdwn +++ /dev/null @@ -1,182 +0,0 @@ -# NAME - -git-annex metadata - sets or gets metadata of a file - -# SYNOPSIS - -git annex metadata `[path ...]` - -# DESCRIPTION - -The content of an annexed file can have any number of metadata fields -attached to it to describe it. Each metadata field can in turn -have any number of values. - -This command can be used to set metadata, or show the currently set -metadata. - -When run without any -s or -t parameters, displays the current metadata. - -Each metadata field has its own "field-lastchanged" metadata, which -contains the date the field was last changed. Unlike other metadata, -this cannot be directly modified by this command. It is updated -automatically. - -Note that the metadata is attached to git-annex key corresponding to the -content of a file, not to a particular filename on a particular git branch. -All files with the same key share the same metadata, which is -stored in the git-annex branch. If a file is modified, the metadata -of the previous version will be copied to the new key when git-annex adds -the modified file. - -# OPTIONS - -* `-g field` / `--get field` - - Get the value(s) of a single field. - - The values will be output one per line, with no other output, so - this is suitable for use in a script. - -* `-s field=value` / `--set field=value` - - Set a field's value, removing any old values. - -* `-s field+=value` / `--set field+=value` - - Add an additional value, preserving any old values. - -* `-s field?=value` / `--set field?=value` - - Set a value, but only if the field does not already have a value set. - -* `-s field-=value` / `--set field-=value` - - Remove a value from a field, leaving any other values that the field has - set. - -* `-r field` / `--remove field` - - Remove all current values of the field. - -* `-t tag` / `--tag tag` - - Set a tag. Note that a tag is just a value of the "tag" field. - -* `-u tag` / `--unset tag` - - Unset a tag. - -* `--remove-all` - - Remove all metadata from the specified files. - - When a file is modified and the new version added, git-annex will copy - over the metadata from the old version of the file. In situations where - you don't want that copied metadata, you can use this option to remove - it. - -* `--force` - - By default, `git annex metadata` refuses to recursively set metadata - throughout the files in a directory. This option enables such recursive - setting. - -* matching options - - The [[git-annex-matching-options]](1) - can be used to control what to act on. - -* `--all` `-A` - - Specify instead of a file to get/set metadata on all known keys. - -* `--branch=ref` - - Specify instead of a file to get/set metadata on all files in the - specified branch or treeish. - -* `--unused` - - Specify instead of a file to get/set metadata on - files found by last run of git-annex unused. - -* `--key=keyname` - - Specify instead of a file to get/set metadata of the specified key. - -* `--json` - - Enable JSON output (and input). Each line is a JSON object. - - The format of the JSON objects changed in git-annex version 6.20160726. - - Example of the new format: - - {"command":"metadata","file":"foo","key":"...","fields":{"author":["bar"],...},"note":"...","success":true} - - Example of the old format, which lacks the inner fields object: - - {"command":"metadata","file":"foo","key":"...","author":["bar"],...,"note":"...","success":true} - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* `--batch` - - Enables batch mode, which can be used to both get, store, and unset - metadata for multiple files or keys. - - Batch currently only supports JSON input. So, you must - enable `--json` along with `--batch`. - - In batch mode, git-annex reads lines from stdin, which contain - JSON objects. It replies to each input annexed file - with an output JSON object. (But if the file is not an annexed file, - an empty line will be output.) - - The format of the JSON sent to git-annex can be the same as the JSON that - it outputs. Or, a simplified version. Only the "file" (or "key") field - is actually necessary. - - For example, to get the current metadata of file foo: - - {"file":"foo"} - - To get the current metadata of the key k: - - {"key":"k"} - - Any metadata fields included in the JSON object will be stored, - replacing whatever values the fields had before. - To unset a field, include it with an empty list of values. - - To change the author of file foo to bar: - - {"file":"foo","fields":{"author":["bar"]}} - - To remove the author of file foo: - - {"file":"foo","fields":{"author":[]}} - -* Also the [[git-annex-common-options]](1) can be used. - -# EXAMPLES - -To set some tags on a file and also its author: - - git annex metadata annexscreencast.ogv -t video -t screencast -s author+=Alice - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-view]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-migrate.mdwn b/doc/git-annex-migrate.mdwn deleted file mode 100644 --- a/doc/git-annex-migrate.mdwn +++ /dev/null @@ -1,76 +0,0 @@ -# NAME - -git-annex migrate - switch data to different backend - -# SYNOPSIS - -git annex migrate `[path ...]` - -# DESCRIPTION - -Changes the specified annexed files to use the default key-value backend -(or the one specified with `--backend`). Only files whose content -is currently available are migrated. - -Note that the content is also still available using the old key after -migration. Use `git annex unused` to find and remove the old key. - -Normally, nothing will be done to files already using the new backend. -However, if a backend changes the information it uses to construct a key, -this can also be used to migrate files to use the new key format. - -When you have multiple repositories that each contain a copy of a file, -it's best to run migrate in all of them. - -# OPTIONS - -* `--backend` - - Specify the new key-value backend to use for migrated data. - -* `--force` - - Force migration of keys that are already using the new backend. - -* file matching options - - The [[git-annex-matching-options]](1) - can be used to specify files to migrate. - -* Also the [[git-annex-common-options]](1) can be used. - -* `--remove-size` - - Keys often include the size of their content, which is generally a useful - thing. In fact, this command defaults to adding missing size information - to keys. With this option, the size information is removed instead. - - One use of this option is to convert URL keys that were added - by `git-annex addurl --fast` to ones that would have been added if - that command was run with the `--relaxed` option. Eg: - - git-annex migrate --remove-size --backend=URL somefile - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-upgrade]](1) - -[[git-annex-backend]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-mirror.mdwn b/doc/git-annex-mirror.mdwn deleted file mode 100644 --- a/doc/git-annex-mirror.mdwn +++ /dev/null @@ -1,100 +0,0 @@ -# NAME - -git-annex mirror - mirror content of files to/from another repository - -# SYNOPSIS - -git annex mirror `[path ...] [--to=remote|--from=remote]` - -# DESCRIPTION - -This causes a destination repository to mirror a source repository. - -Each specified file in the source repository is mirrored to the destination -repository. If a file's content is present in the source repository, it is -copied to the destination repository. If a file's content is not present in -the source repository, it will be dropped from the destination repository -when the numcopies setting allows. - -Note that mirror does not sync the git repository, but only the file -contents. Use [[git-annex-sync]](1) for that. - -# OPTIONS - -* `--to=remote` - - Use the local repository as the source repository, and mirror its contents - to the remote. - -* `--from=remote` - - Use the remote as the source repository, and mirror its contents to the local - repository. - -* `--jobs=N` `-JN` - - Enables parallel transfers 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. - -* `--all` `-A` - - Mirror all objects stored in the git annex, not only objects used by - currently existing files. - - However, this bypasses checking the .gitattributes annex.numcopies - setting when dropping files. - - This is the default behavior when running git-annex in a bare repository. - -* `--branch=ref` - - Operate on files in the specified branch or treeish. - - Like --all, this bypasses checking the .gitattributes annex.numcopies - setting when dropping files. - -* `--unused` - - Operate on files found by last run of git-annex unused. - -* `--failed` - - Operate on files that have recently failed to be transferred. - -* matching options - - The [[git-annex-matching-options]](1) - can be used to control what to mirror. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - - Note that unlike all other commands that support `--json`, this command - outputs different types of json objects in different circumstances. - -* `--json-progress` - - Include progress objects in JSON output. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-sync]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-move.mdwn b/doc/git-annex-move.mdwn deleted file mode 100644 --- a/doc/git-annex-move.mdwn +++ /dev/null @@ -1,141 +0,0 @@ -# NAME - -git-annex move - move content of files to/from another repository - -# SYNOPSIS - -git annex move `[path ...] [--from=remote|--to=remote|--to=here]` - -# DESCRIPTION - -Moves the content of files from or to another remote. - -With no parameters, operates on all annexed files in the current directory. -Paths of files or directories to operate on can be specified. - -# OPTIONS - -* `--from=remote` - - Move the content of files from the specified remote to the local repository. - -* `--to=remote` - - Move the content of files from the local repository to the specified remote. - -* `--to=here` - - Move the content of files from all reachable remotes to the local - repository. - -* `--from=remote1 --to=remote2` - - Move the content of files that are in remote1 to remote2. Does not change - what is stored in the local repository. - - This is implemented by first downloading the content from remote1 to the - local repository (if not already present), then sending it to remote2, and - then deleting the content from the local repository (if it was not present - to start with). - -* `--force` - - Override numcopies and required content checking, and always remove - files from the source repository once the destination repository has a - copy. - - Note that, even without this option, you can move the content of a file - from one repository to another when numcopies is not satisfied, as long - as the move does not result in there being fewer copies. - -* `--jobs=N` `-JN` - - Enables parallel transfers 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 when using --from with --to, twice this many jobs will - run at once, evenly split between the two remotes. - -* `--all` `-A` - - Rather than specifying a filename or path to move, this option can be - used to move all available versions of all files. - - This is the default behavior when running git-annex in a bare repository. - -* `--branch=ref` - - Operate on files in the specified branch or treeish. - -* `--unused` - - Operate on files found by last run of git-annex unused. - -* `--failed` - - Operate on files that have recently failed to be transferred. - -* `--key=keyname` - - Use this option to move a specified key. - -* matching options - - The [[git-annex-matching-options]](1) - can be used to control what to move. - -* `--batch` - - Enables batch mode, in which lines containing names of files to move - are read from stdin. - - As each specified file is processed, the usual progress output is - displayed. If a file's content does not need to be moved, - or it does not match specified matching options, or it - is not an annexed file, a blank line is output in response instead. - - Since the usual output while moving a file is verbose and not - machine-parseable, you may want to use --json in combination with - --batch. - -* `--batch-keys` - - This is like `--batch` but the lines read from stdin are parsed as keys. - -* `-z` - - Makes batch input be delimited by nulls instead of the usual newlines. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-progress` - - Include progress objects in JSON output. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-get]](1) - -[[git-annex-copy]](1) - -[[git-annex-drop]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-multicast.mdwn b/doc/git-annex-multicast.mdwn deleted file mode 100644 --- a/doc/git-annex-multicast.mdwn +++ /dev/null @@ -1,97 +0,0 @@ -# NAME - -git-annex multicast - multicast file distribution - -# SYNOPSIS - -git annex multicast [options] - -# DESCRIPTION - -Multicast allows files to be broadcast to multiple receivers, -typically on a single local network. - -The uftp program is used for multicast. - - -# OPTIONS - -* `--gen-address` - - Generates a multicast encryption key and stores a corresponding multicast - address to the git-annex branch. - -* `--send [file]` - - Sends the specified files to any receivers whose multicast addresses - are stored in the git-annex branch. - - When no files are specified, all annexed files in the current directory - and subdirectories are sent. - - The [[git-annex-matching-options]](1) can be used to control which files to - send. For example: - - git annex multicast send . --not --copies 2 - -* `--receive` - - Receives files from senders whose multicast addresses - are stored in the git-annex brach. - - As each file is received, its filename is displayed. This is the filename - that the sender used; the local working tree may use a different name - for the file, or not contain a link to the file. - - This command continues running, until it is interrupted by you pressing - ctrl-c. - - Note that the configured annex.diskreserve is not honored by this - command, because `uftpd` receives the actual files, and can receive - any size file. - -* `--uftp-opt=option` `-Uoption` - - Pass an option on to the uftp/uftpd command. May be specified multiple - times. - - For example, to broadcast at 50 Mbps: - - git annex multicast send -U-R -U50000 - -* Also the [[git-annex-common-options]](1) can be used. - -# EXAMPLE - -Suppose a teacher wants to multicast files to students in a classroom. - -This assumes that the teacher and students have cloned a git-annex -repository, and both can push changes to its git-annex branch, -or otherwise push changes to each-other. - -First, the teacher runs `git annex multicast --gen-address; git annex sync` - -Next, students each run `git annex multicast --gen-address; git annex sync` - -Once all the students have generated addresses, the teacher runs -`git annex sync` once more. (Now the students all have received the -teacher's address, and the teacher has received all the student's addresses.) - -Next students each run `git annex multicast --receive` - -Finally, once the students are all listening (ahem), teacher runs -`git annex multicast --send` - -# SEE ALSO - -[[git-annex]](1) - -uftp(1) - -uftpd(1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-numcopies.mdwn b/doc/git-annex-numcopies.mdwn deleted file mode 100644 --- a/doc/git-annex-numcopies.mdwn +++ /dev/null @@ -1,45 +0,0 @@ -# NAME - -git-annex numcopies - configure desired number of copies - -# SYNOPSIS - -git annex numcopies `N` - -# DESCRIPTION - -Tells git-annex how many copies it should preserve of files, over all -repositories. The default is 1. - -Run without a number to get the current value. - -This configuration is stored in the git-annex branch, so it will be seen -by all clones of the repository. It can be overridden on a per-file basis -by the annex.numcopies setting in .gitattributes files, or can be -overridden temporarily with the --numcopies option. - -When git-annex is asked to drop a file, it first verifies that the -number of copies can be satisfied among all the other -repositories that have a copy of the file. - -In unusual situations, involving special remotes that do not support -locking, and concurrent drops of the same content from multiple -repositories, git-annex may violate the numcopies setting. It still -guarantees at least 1 copy is preserved. This can be configured by -using [[git-annex-mincopies]](1) - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) -[[git-annex-mincopies]](1) -[[git-annex-config]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-p2p.mdwn b/doc/git-annex-p2p.mdwn deleted file mode 100644 --- a/doc/git-annex-p2p.mdwn +++ /dev/null @@ -1,82 +0,0 @@ -# NAME - -git-annex p2p - configure peer-2-peer links between repositories - -# SYNOPSIS - -git annex p2p [options] - -# DESCRIPTION - -This command can be used to link git-annex repositories over peer-2-peer -networks. - -Currently, the only P2P network supported by git-annex is Tor hidden -services. - -# OPTIONS - -* `--pair` - - Run this in two repositories to pair them together over the P2P network. - - This will print out a code phrase, like "3-mango-elephant", and - will prompt for you to enter the code phrase from the other repository. - - Once code phrases have been exchanged, the two repositories will - be paired. A git remote will be created for the other repository, - with a name like "peer1". - - This uses [Magic Wormhole](https://github.com/warner/magic-wormhole) - to verify the code phrases and securely communicate the P2P addresses of - the repositories, so you will need it installed on both computers that are - being paired. - - This feature was present in a broken form in git-annex versions - before version 6.20180705. Make sure that a new enough git-annex - is installed on both computers that are being paired. - -* `--gen-addresses` - - Generates addresses that can be used to access this git-annex repository - over the available P2P networks. The address or addresses is output to - stdout. - - Note that anyone who knows these addresses can access your - repository over the P2P networks. - - This can be run repeatedly, in order to give different addresses - out to different people. - -* `--link` - - Sets up a git remote that is accessed over a P2P network. - - This will prompt for an address to be entered; you should paste in the - address that was generated by --gen-addresses in the remote repository. - - Defaults to making the git remote be named "peer1", "peer2", - etc. This can be overridden with the `--name` option. - -* `--name` - - Specify a name to use when setting up a git remote with `--link` - or `--pair`. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-enable-tor]](1) - -[[git-annex-remotedaemon]](1) - -wormhole(1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-pre-commit.mdwn b/doc/git-annex-pre-commit.mdwn deleted file mode 100644 --- a/doc/git-annex-pre-commit.mdwn +++ /dev/null @@ -1,32 +0,0 @@ -# NAME - -git-annex pre-commit - run by git pre-commit hook - -# SYNOPSIS - -git annex pre-commit `[path ...]` - -# DESCRIPTION - -This is meant to be called from git's pre-commit hook. `git annex init` -automatically creates a pre-commit hook using this. - -Fixes up symlinks that are staged as part of a commit, to ensure they -point to annexed content. - -When in a view, updates metadata to reflect changes -made to files in the view. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-preferred-content.mdwn b/doc/git-annex-preferred-content.mdwn deleted file mode 100644 --- a/doc/git-annex-preferred-content.mdwn +++ /dev/null @@ -1,317 +0,0 @@ -# NAME - -git-annex-preferred-content - which files are wanted in a repository - -# DESCRIPTION - -Each repository has a preferred content setting, which specifies content -that the repository wants to have present. These settings can be configured -using `git annex vicfg` or `git annex wanted`. -They are used by the `--auto` option, by `git annex sync --content`, -and by the git-annex assistant. - -While preferred content expresses a preference, it can be overridden -by simply using `git annex drop`. On the other hand, required content -settings are enforced; `git annex drop` will refuse to drop a file if -doing so would violate its required content settings. A repository's -required content can be configured using `git annex vicfg` or -`git annex required`. - -# SYNTAX - -Preferred content expressions use a similar syntax to -the [[git-annex-matching-options]](1), without the dashes. -For example: - - exclude=archive/* and (include=*.mp3 or smallerthan=1mb) - -The idea is that you write an expression that files are matched against. If -a file matches, the repository wants to store its content. If it doesn't, -the repository wants to drop its content (if there are enough copies -elsewhere to allow removing it). - -# EXPRESSIONS - -* `include=glob` / `exclude=glob` - - Match files to include, or exclude. - - While the command-line options --include=glob and --exclude=glob match - files relative to the current directory, preferred content expressions - match files relative to the top of the git repository. - - A glob is something like `foo.*` or `b?r`. - Globs can also contain character classes, - like `foo[Bb]ar`, as well as additional POSIX character classes like - `[[:space:]]`. Which is useful, since a glob in a preferred content - expression cannot contain spaces. See the `glob(7)` man page for more - about globs. - - For example, suppose you put files into `archive` directories - when you're done with them. Then you could configure your laptop to prefer - to not retain those files, like this: `exclude=*/archive/*` - - When a subdirectory is being exported or imported to a special remote (see - [[git-annex-export]](1)) and [[git-annex-import]](1), these match relative - to the top of the subdirectory. - - Note that, when a command is run with the `--all` option, or in a bare - repository, there is no filename associated with an annexed object, - and so "include=" and "exclude=" will not match. - -* `copies=number` - - Matches only files that git-annex believes to have the specified number - of copies, or more. Note that it does not check remotes to verify that - the copies still exist. - - To decide if content should be dropped, git-annex evaluates the preferred - content expression under the assumption that the content has *already* been - dropped. If the content would not be wanted then, the drop can be done. - So, for example, `copies=2` in a preferred content expression lets - content be dropped only when there are currently 3 copies of it, including - the repo it's being dropped from. This is different than running `git annex - drop --copies=2`, which will drop files that currently have 2 copies. - -* `copies=trustlevel:number` - - Matches only files that git-annex believes have the specified number - copies, on remotes with the specified trust level. For example, - `copies=trusted:2` - - To match any trust level at or higher than a given level, - use `trustlevel+`. For example, `copies=semitrusted+:2` - -* `copies=groupname:number` - - Matches only files that git-annex believes have the specified number of - copies, on remotes in the specified group. For example, - `copies=archive:2` - - Preferred content expressions have no equivalent to the `--in` - option, but groups can accomplish similar things. You can add - repositories to groups, and match against the groups in a - preferred content expression. So rather than `--in=usbdrive`, - put all the USB drives into a "transfer" group, and use - `copies=transfer:1` - -* `lackingcopies=number` - - Matches only files that git-annex believes need the specified number or - more additional copies to be made in order to satisfy their numcopies - settings. - -* `approxlackingcopies=number` - - Like lackingcopies, but does not look at .gitattributes annex.numcopies - settings. This makes it significantly faster. - -* `inbackend=backendname` - - Matches only files whose content is stored using the specified key-value - backend. - - See [[git-annex-backends]](1) for information about available backends. - -* `securehash` - - Matches only files whose content is hashed using a cryptographically - secure function. - -* `inallgroup=groupname` - - Matches only files that git-annex believes are present in all repositories - in the specified group. - -* `onlyingroup=groupname` - - Matches files that git-annex believes are present in at least one - repository that is in the specified group, and are not present in any - repositories that are not in the specified group. - -* `smallerthan=size` / `largerthan=size` - - Matches only files whose content is smaller than, or larger than the - specified size. - - The size can be specified with any commonly used units, for example, - "0.5 gb" or "100 KiloBytes" - -* `metadata=field=glob` - - Matches only files that have a metadata field attached with a value that - matches the glob. The values of metadata fields are matched case - insensitively. - - A glob is something like `foo.*` or `b?r`. - Globs can also contain character classes, - like `foo[Bb]ar`, as well as additional POSIX character classes like - `[[:space:]]`. Which is useful, since a glob in a preferred content - expression cannot contain spaces. See the `glob(7)` man page for more - about globs. - - To match a tag "done", use `metadata=tag=done` - - To match author metadata, use `metadata=author=*Smith` - -* `metadata=fieldnumber` -* `metadata=field<=number` / `metadata=field>=number` - - Matches only files that have a metadata field attached with a value that - is a number and is less than or greater than the specified number. - - To match PDFs with between 100 and 200 pages (assuming something has set - that metadata), use `metadata=pagecount>=100 and metadata=pagecount<=200` - -* `present` - - Makes content be wanted if it's present, but not otherwise. - - This leaves it up to you to use git-annex manually - to move content around. You can use this to avoid preferred content - settings from affecting a subdirectory. For example: - `auto/* or (include=ad-hoc/* and present)` - - Note that `not present` is a very bad thing to put in a preferred content - expression. It'll make it want to get content that's not present, and - drop content that is present! Don't go there.. - -* `inpreferreddir` - - Makes content be preferred if it's in a directory (located anywhere - in the tree) with a particular name. - - The name of the directory can be configured using - `git annex enableremote $remote preferreddir=$dirname` - - (If no directory name is configured, it uses "public" by default.) - - Note that, when a command is run with the `--all` option, or in a bare - repository, there is no filename associated with an annexed object, - and so "inpreferreddir" will not match. - -* `standard` - - git-annex comes with some built-in preferred content expressions, that - can be used with repositories that are in some standard groups - such as "client" and "transfer". - - When a repository is in exactly one such group, you can use the "standard" - keyword in its preferred content expression, to match whatever content - the group's expression matches. - - Most often, the whole preferred content expression is simply "standard". - But, you can do more complicated things, for example: - `standard or include=otherdir/*` - -* `groupwanted` - - The "groupwanted" keyword can be used to refer to a preferred content - expression that is associated with a group, as long as there is exactly - one such expression amoung the groups a repository is in. This is like - the "standard" keyword, but you can configure the preferred content - expressions using `git annex groupwanted`. - - When writing a groupwanted preferred content expression, - you can use all the keywords documented here, including "standard". - (But not "groupwanted".) - - For example, to make a variant of the standard client preferred content - expression that does not want files in the "out" directory, you - could run: `git annex groupwanted client "standard and exclude=out/*"` - - Then repositories that are in the client group and have their preferred - content expression set to "groupwanted" will use that, while - other client repositories that have their preferred content expression - set to "standard" will use the standard expression. - - Or, you could make a new group, with your own custom preferred content - expression tuned for your needs, and every repository you put in this - group and make its preferred content be "groupwanted" will use it. - - For example, the archive group only wants to archive 1 copy of each file, - spread among every repository in the group. - Here's how to configure a group named redundantarchive, that instead - wants to contain 3 copies of each file: - - git annex groupwanted redundantarchive "not (copies=redundantarchive:3)" - for repo in foo bar baz; do - git annex group $repo redundantarchive - git annex wanted $repo groupwanted - done - -* `unused` - - Matches only keys that `git annex unused` has determined to be unused. - - This is related the the --unused option. - However, putting `unused` in a preferred content expression - doesn't make git-annex consider those unused keys. So when git-annex is - only checking preferred content expressions against files in the - repository (which are obviously used), `unused` in a preferred - content expression won't match anything. - - So when is `unused` useful in a preferred content expression? - - Using `git annex sync --content --all` will operate on all files, - including unused ones, and take `unused` in preferred content expressions - into account. - - The git-annex assistant periodically scans for unused files, and - moves them to some repository whose preferred content expression - says it wants them. (Or, if annex.expireunused is set, it may just delete - them.) - -* `anything` - - Always matches. - -* `nothing` - - Never matches. (Same as "not anything") - -* `not expression` - - Inverts what the expression matches. For example, `not include=archive/*` - is the same as `exclude=archive/*` - -* `and` / `or` / `( expression )` - - These can be used to build up more complicated expressions. - -# TESTING - -To check at the command line which files are matched by a repository's -preferred content settings, you can use the --want-get and --want-drop -options. - -For example, git annex find --want-get --not --in . will find all the files -that git annex get --auto will want to get, and git annex find --want-drop --in -. will find all the files that git annex drop --auto will want to drop. - -The --explain option can be used to understand why a complex preferred -content expression matches or fails to match. The expression will -be displayed, with each term followed by "[TRUE]" or "[FALSE]" to indicate -the value. Irrelevant terms will be ommitted from the explanation, -for example `"exclude=* and copies=1"` will be displayed as -`"exclude=*[FALSE]"` - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-vicfg]](1) - -[[git-annex-wanted]](1) - - - - - -# AUTHOR - -Joey Hess - - - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-proxy.mdwn b/doc/git-annex-proxy.mdwn deleted file mode 100644 --- a/doc/git-annex-proxy.mdwn +++ /dev/null @@ -1,25 +0,0 @@ -# NAME - -git-annex proxy - safely bypass direct mode guard (deprecated) - -# SYNOPSIS - -git annex proxy `-- git cmd [options]` - -# DESCRIPTION - -This command was for use in a direct mode repository, and such -repositories are automatically updated to use an adjusted unlocked branch. -So, there's no reason to use this command any longer. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-direct]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-pull.mdwn b/doc/git-annex-pull.mdwn deleted file mode 100644 --- a/doc/git-annex-pull.mdwn +++ /dev/null @@ -1,145 +0,0 @@ -# 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, `-g`, `--content` - - Use `--no-content` or `-g` 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) - -[[git-annex-satisfy]](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 deleted file mode 100644 --- a/doc/git-annex-push.mdwn +++ /dev/null @@ -1,143 +0,0 @@ -# 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`, `-g`, `--content` - - Use `--no-content` or `-g` 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. - -* `--cleanup` - - Removes the local and remote `synced/` branches, which were created - and pushed by `git-annex push` or `git-annex sync`. This option - prevents all other activities. - - This can come in handy when you've pushed a change to remotes and now - want to reset your master branch back before that change. So you - run `git reset` and force-push the master branch to remotes, only - to find that the next `git annex merge` or `git annex pull` brings the - changes back. Why? Because the `synced/master` branch is hanging - around and still has the change in it. Cleaning up the `synced/` branches - prevents that problem. - -* 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) - -[[git-annex-satisfy]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-readpresentkey.mdwn b/doc/git-annex-readpresentkey.mdwn deleted file mode 100644 --- a/doc/git-annex-readpresentkey.mdwn +++ /dev/null @@ -1,32 +0,0 @@ -# NAME - -git-annex readpresentkey - read records of where key is present - -# SYNOPSIS - -git annex readpresentkey `key uuid` - -# DESCRIPTION - -This plumbing-level command reads git-annex's records about whether -the specified key's content is present in the remote with the specified -uuid. - -It exits 0 if the key is recorded to be present and 1 if not. - -Note that this does not do an active check to verify if the key -is present. To do such a check, use [[git-annex-checkpresentkey]](1) - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-registerurl.mdwn b/doc/git-annex-registerurl.mdwn deleted file mode 100644 --- a/doc/git-annex-registerurl.mdwn +++ /dev/null @@ -1,75 +0,0 @@ -# NAME - -git-annex registerurl - registers an url for a key - -# SYNOPSIS - -git annex registerurl `[key url]` - -# DESCRIPTION - -This plumbing-level command can be used to register urls where a -key can be downloaded from. - -No verification is performed of the url's contents. - -Normally the key is a git-annex formatted key. However, to make it easier -to use this to add urls, if the key cannot be parsed as a key, and is a -valid url, an URL key is constructed from the url. - -Registering an url also makes git-annex treat the key as present in the -special remote that claims it. (Usually the web special remote.) - -# OPTIONS - -* `--remote=name|uuid` - - Indicate that the url is expected to be claimed by the specified remote. - If some other remote claims the url instead, registering it will fail. - - Note that `--remote=web` will prevent any other remote from claiming - the url. - -* `--batch` - - In batch input mode, lines are read from stdin, and each line - should contain a key and url, separated by a single space. - - For backwards compatability with old git-annex before this option - was added, when no key and url pair are specified on the command line, - batch input is used, the same as if the --batch option were - specified. It is however recommended to use --batch. - -* `-z` - - When in batch mode, the input is delimited by nulls instead of the usual - newlines. - - (Note that for this to be used, you have to explicitly enable batch mode - with `--batch`) - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-addurl]](1) - -[[git-annex-unregisterurl]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-reinit.mdwn b/doc/git-annex-reinit.mdwn deleted file mode 100644 --- a/doc/git-annex-reinit.mdwn +++ /dev/null @@ -1,52 +0,0 @@ -# NAME - -git-annex reinit - initialize repository, reusing old UUID - -# SYNOPSIS - -git annex reinit `uuid|description` - -# DESCRIPTION - -Normally, initializing a repository generates a new, unique identifier -(UUID) for that repository. Occasionally it may be useful to reuse a -UUID -- for example, if a repository got deleted, and you're -setting it back up. - -Use this with caution; it can be confusing to have two existing -repositories with the same UUID. - -Make sure you run `git annex fsck` after changing the UUID of a -repository to make sure location tracking information is recorded -correctly. - -Like `git annex init`, this attempts to enable any special remotes -that are configured with autoenable=true. - -# OPTIONS - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-init]](1) - -[[git-annex-fsck]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-reinject.mdwn b/doc/git-annex-reinject.mdwn deleted file mode 100644 --- a/doc/git-annex-reinject.mdwn +++ /dev/null @@ -1,97 +0,0 @@ -# NAME - -git-annex reinject - inject content of file back into annex - -# SYNOPSIS - -git annex reinject `[src dest]` - -git annex reinject --known `[src]` - -# DESCRIPTION - -Moves the content of the src file or files into the annex. -Only known file contents will be reinjected. Any unknown src files will -be left unchanged. - -This can be useful if you have obtained the content of a file from -elsewhere and want to put it in the local annex. For example, if a file's -content has been lost and you have a backup, you can restore the backup and -reinject it into your local repository. - -There are two ways to use this command. Specifying a src file and the name -of a dest file (located inside the repository's working tree) -injects the src file as the content of the dest file. - - git annex reinject /tmp/foo.iso foo.iso - -Or the `--known` option can be used to reinject all known src files, without -needing to specify the dest file. - - git annex reinject --known /tmp/*.iso - -# OPTIONS - -* `--known` - - With this option, each specified src file is hashed using the default - key-value backend (or the one specified with `--backend`), and if git-annex - has a record of the resulting key having been in the annex before, the - content is reinjected. - - Note that, when using a key-value backend that includes the filename - extension in the key, this will only work if the src files have the same - extensions as the files with the same content that was originally added - to git-annex. - - Note that this will reinject old versions of files that have been - modified or deleted from the current git branch. - Use [[git-annex-unused]](1) to detect when such old and potentially - unused files have been reinjected. - -* `--backend` - - Specify the key-value backend to use when checking if a file is known - with the `--known` option. - -* `--guesskeys` - - With this option, each specified source file is checked to see if it - has the name of a git-annex key, and if so it is imported as the content - of that key. - - This can be used to pluck git-annex objects out of `lost+found`, - as long as the original filename has not been lost, - and is particularly useful when using key-value backends that don't hash - to the content of a file. - - When the key-value backend does support hashing, the content of the file - is verified before importing it. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-add]](1) - -[[git-annex-unused]](1) - -[[git-annex-fsck]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-rekey.mdwn b/doc/git-annex-rekey.mdwn deleted file mode 100644 --- a/doc/git-annex-rekey.mdwn +++ /dev/null @@ -1,59 +0,0 @@ -# NAME - -git-annex rekey - change keys used for files - -# SYNOPSIS - -git annex rekey `[file key ...]` - -# DESCRIPTION - -This plumbing-level command is similar to migrate, but you specify -both the file, and the new key to use for it. - -Multiple pairs of file and key can be given in a single command line. - -Note that, unlike `git-annex migrate`, this does not copy over metadata, -urls, and other such information from the old to the new key - -# OPTIONS - -* `--force` - - Allow rekeying of even files whose content is not currently available. - Use with caution. - -* `--batch` - - Enables batch mode, in which lines are read from stdin. - Each line should contain the file, and the new key to use for that file, - separated by a single space. - -* `-z` - - Makes the `--batch` input be delimited by nulls instead of the usual - newlines. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-migrate]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-remotedaemon.mdwn b/doc/git-annex-remotedaemon.mdwn deleted file mode 100644 --- a/doc/git-annex-remotedaemon.mdwn +++ /dev/null @@ -1,58 +0,0 @@ -# NAME - -git-annex remotedaemon - persistent communication with remotes - -# SYNOPSIS - -git annex remotedaemon - -# DESCRIPTION - -The remotedaemon provides persistent communication with remotes. - -Several types of remotes are supported: - -For ssh remotes, the remotedaemon tries to maintain a connection to the -remote git repository, and uses git-annex-shell notifychanges to detect -when the remote git repository has changed, and fetches changes from it. -For this to work, the git remote must have [[git-annex-shell]](1) -installed, with notifychanges support. The first version of git-annex-shell -that supports it is 5.20140405. - -For tor-annex remotes, the remotedaemon runs a tor hidden service, -accepting connections from other nodes and serving up the contents of the -repository. This is only done if you first run `git annex enable-tor`. -Use `git annex p2p` to configure access to tor-annex remotes. - -Note that when `remote..annex-pull` is set to false, the remotedaemon -will avoid fetching changes from that remote. - -# OPTIONS - -* `--foreground` - - Don't fork to the background, and communicate on stdin/stdout using a - simple textual protocol. The assistant runs the remotedaemon this way. - - Commands in the protocol include LOSTNET, which tells the remotedaemon - that the network connection has been lost, and causes it to stop any TCP - connctions. That can be followed by RESUME when the network connection - comes back up. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-assistant]](1) - -[[git-annex-enable-tor]](1) - -[[git-annex-p2p]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-renameremote.mdwn b/doc/git-annex-renameremote.mdwn deleted file mode 100644 --- a/doc/git-annex-renameremote.mdwn +++ /dev/null @@ -1,47 +0,0 @@ -# NAME - -git-annex renameremote - changes name of a special remote - -# SYNOPSIS - -git annex renameremote `name|uuid|desc newname` - -# DESCRIPTION - -Changes the name that is used to enable a special remote. - -Normally the current name is used to identify the special remote to rename, -but its uuid or description can also be used. - -This is especially useful when an old special remote used a name, and now you -want to use that name for a new special remote. `git annex initremote` -won't let you create a remote with a conflicting name, so rename the old -remote first. - - git annex renameremote phone lost-phone - git annex initremote phone ... - -This only updates the name that git-annex has stored for use -by `git annex enableremote`. It does not update the git config stanza -for the special remote to use the new name, but of course you can edit -the git config if you want to rename it there. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-initremote]](1) - -[[git-annex-enableremote]](1) - -[[git-annex-configremote]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-repair.mdwn b/doc/git-annex-repair.mdwn deleted file mode 100644 --- a/doc/git-annex-repair.mdwn +++ /dev/null @@ -1,59 +0,0 @@ -# NAME - -git-annex repair - recover broken git repository - -# SYNOPSIS - -git annex repair - -# DESCRIPTION - -This can repair many of the problems with git repositories that `git fsck` -detects, but does not itself fix. It's useful if a repository has become -badly damaged. One way this can happen is if a repository used by git-annex -is on a removable drive that gets unplugged at the wrong time. - -This command can actually be used inside git repositories that do not -use git-annex at all; when used in a repository using git-annex, it -does additional repairs of the git-annex branch. - -It works by deleting any corrupt objects from the git repository, and -retrieving all missing objects it can from the remotes of the repository. - -If that is not sufficient to fully recover the repository, it can also -reset branches back to commits before the corruption happened, delete -branches that are no longer available due to the lost data, and remove any -missing files from the index. It will only do this if run with the -`--force` option, since that rewrites history and throws out missing data. -Note that the `--force` option never touches tags, even if they are no -longer usable due to missing data. - -After running this command, you will probably want to run `git fsck` to -verify it fixed the repository. Note that fsck may still complain about -objects referenced by the reflog, or the stash, if they were unable to be -recovered. This command does not try to clean up either the reflog or the -stash. - -It is also a good idea to run `git annex fsck --fast` after this command, -to make sure that the git-annex branch reflects reality. - -# OPTIONS - -* `--force` - - Enable repair actions that involve deleting data that has been - lost due to git repository corruption. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-fsck]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-required.mdwn b/doc/git-annex-required.mdwn deleted file mode 100644 --- a/doc/git-annex-required.mdwn +++ /dev/null @@ -1,49 +0,0 @@ -# NAME - -git-annex required - get or set required content expression - -# SYNOPSIS - -git annex required `repository [expression]` - -# DESCRIPTION - -When run with an expression, configures the content that is required -to be held in the archive. - -For example: - - git annex required . "include=*.mp3 or include=*.ogg" - -Without an expression, displays the current required content setting -of the repository. - -While [[git-annex-wanted]](1) is just a preference, this designates content -that should really not be removed. For example a file that is `wanted` can -be removed with `git annex drop`, but if that file is `required`, it would -need to be removed with `git annex drop --force`. - -Also, `git-annex fsck` will warn about required contents that are not -present. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# NOTES - -The `required` command was added in git-annex 5.20150420. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-wanted]](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-resolvemerge.mdwn b/doc/git-annex-resolvemerge.mdwn deleted file mode 100644 --- a/doc/git-annex-resolvemerge.mdwn +++ /dev/null @@ -1,70 +0,0 @@ -# NAME - -git-annex resolvemerge - resolve merge conflicts - -# SYNOPSIS - -git annex resolvemerge - -# DESCRIPTION - -Automatically resolves a conflicted merge. This is done -automatically when using `git annex sync` or `git annex merge`. - -When two trees being merged contain conflicting versions of an annexed -file, the merge conflict will be resolved by adding both versions to the -tree, using variants of the filename. - -When one tree modified the file, and the other tree deleted the file, -the merge conflict will be resolved by adding the modified file using a -variant of the filename, leaving the original filename deleted. - -When the merge conflict involves a file that is annexed in one -tree, but is not annexed in the other tree, it is -resolved by keeping the non-annexed file as-is, and adding the annexed -version using a variant of the filename. - -Note that only merge conflicts that involve one or more annexed files -are resolved. Merge conflicts between two files that are not annexed -will not be automatically resolved. - -# EXAMPLES - -Suppose Alice commits a change to annexed file `foo`, and Bob commits -a different change to the same file `foo`. - -Merging between them will then fail, and git will present the -merge conflict as a file `foo` pointing to one version of the -git-annex symlink, with `git status` indicating that `foo` has an -unresolved conflict. - -Running `git annex resolvemerge` in this situation will resolve the merge -conflict, by replacing the file `foo` with files named like -`foo.variant-c696` and `foo.variant-f16a`. One of the files has the content -that Alice committed, and the other has the content that Bob committed. - -The user can then examine the two variants of the file, and either merge -the two changes into a single file, or rename one of them back to `foo` -and delete the other. - -Now suppose Alice commits a change to annexed file `bar`, while Bob commits -a deletion of the same file `bar`. Merging will fail. Running -`git annex resolvemerge` in this situation will resolve the merge conflict -by making a file with a name like `bar.variant-421f` containing Alice's -version. The `bar` file remains deleted. The user can later examine the -variant of the file and either rename it back to `bar`, or decide to delete -it too. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-restage.mdwn b/doc/git-annex-restage.mdwn deleted file mode 100644 --- a/doc/git-annex-restage.mdwn +++ /dev/null @@ -1,34 +0,0 @@ -# NAME - -git-annex restage - restages unlocked files in the git index - -# SYNOPSIS - -git annex restage - -# DESCRIPTION - -Since getting or dropping an unlocked file modifies the file in the work -tree, git needs to be told that the modification does not change the -content that it has recorded (the annex pointer). Restaging the file -accomplishes that. - -You do not normally need to run this command, because usually git-annex -is able to restage unlocked files itself. There are some situations -where git-annex needs to restage a file, but the git index is locked, -and so it cannot. It will then display a warning suggesting you run this -command. - -It's safe to run this command even after you have made a modification to an -unlocked file. - -# SEE ALSO - -[[git-annex]](1) -[[git-annex-smudge]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-rmurl.mdwn b/doc/git-annex-rmurl.mdwn deleted file mode 100644 --- a/doc/git-annex-rmurl.mdwn +++ /dev/null @@ -1,53 +0,0 @@ -# NAME - -git-annex rmurl - record file is not available at url - -# SYNOPSIS - -git annex rmurl `[file url ..]` - -# DESCRIPTION - -Record that the file is no longer available at the url. - -Removing the last web url will make git-annex no longer treat content as being -present in the web special remote. If some other special remote -claims the url, unregistering the url will not update presence information -for it, because the content may still be present on the remote. - -# OPTIONS - -* `--batch` - - Enables batch mode, in which lines are read from stdin. - Each line should contain the file, and the url to remove from that file, - separated by a single space. - -* `-z` - - Makes the `--batch` input be delimited by nulls instead of the usual - newlines. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-addurl]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-satisfy.mdwn b/doc/git-annex-satisfy.mdwn deleted file mode 100644 --- a/doc/git-annex-satisfy.mdwn +++ /dev/null @@ -1,66 +0,0 @@ -# NAME - -git-annex satisfy - transfer and drop content as configured - -# SYNOPSIS - -git annex satisfy `[remote ...]` - -# DESCRIPTION - -This transfers and drops content of annexed files to work toward satisfying -the preferred content settings of the local repository and remotes. - -It does the same thing as `git-annex sync --content` without the pulling -and pushing of git repositories, and without changing the trees that are -imported to or exported from special remotes. - -# OPTIONS - -* `[remote]` - - By default this command operates on all remotes, 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 operate on. - -* `--content-of=path` `-C path` - - Operate on only files in the specified path. The default is to operate on - all files in the working tree. - - This option can be repeated multiple times with different paths. - -* `--jobs=N` `-JN` - - Enables parallel processing 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. - -* `--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. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](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-schedule.mdwn b/doc/git-annex-schedule.mdwn deleted file mode 100644 --- a/doc/git-annex-schedule.mdwn +++ /dev/null @@ -1,55 +0,0 @@ -# NAME - -git-annex schedule - get or set scheduled jobs - -# SYNOPSIS - -git annex schedule `repository [expression]` - -# DESCRIPTION - -The [[git-annex-assistant]](1) daemon can be configured to run scheduled jobs. -This is similar to cron and anacron (and you can use them if you prefer), -but has the advantage of being integrated into git-annex, and so being able -to e.g., fsck a repository on a removable drive when the drive gets -connected. - -When run with an expression, configures scheduled jobs to run at a -particular time. This can be used to make the assistant periodically run -incremental fscks. - -When run without an expression, outputs the current scheduled jobs for -the repository. - -# EXPRESSIONS - -These actions are available: "fsck self", "fsck UUID" (where UUID -is the UUID of a remote to fsck). After the action comes the duration -to allow the action to run, and finally the schedule of when to run it. - -To schedule multiple jobs, separate them with "; ". - - Some examples: - - fsck self 30m every day at any time - fsck self 1h every month at 3 AM - fsck self 1h on day 1 of every month at any time - fsck self 1h every week divisible by 2 at any time - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-assistant]](1) - -[[git-annex-expire]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-semitrust.mdwn b/doc/git-annex-semitrust.mdwn deleted file mode 100644 --- a/doc/git-annex-semitrust.mdwn +++ /dev/null @@ -1,46 +0,0 @@ -# NAME - -git-annex semitrust - return repository to default trust level - -# SYNOPSIS - -git annex semitrust `[repository ...]` - -# DESCRIPTION - -Returns a repository to the default semi trusted state. - -Repositories can be specified using their remote name, their -description, or their UUID. For the current repository, use "here". - -# OPTIONS - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-trust]](1) - -[[git-annex-untrust]](1) - -[[git-annex-dead]](1) - -[[git-annex-expire]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-setkey.mdwn b/doc/git-annex-setkey.mdwn deleted file mode 100644 --- a/doc/git-annex-setkey.mdwn +++ /dev/null @@ -1,33 +0,0 @@ -# NAME - -git-annex setkey - sets annexed content for a key - -# SYNOPSIS - -git annex setkey key file - -# DESCRIPTION - -This plumbing-level command makes the content of the specified key -be set to the specified file. The file is moved into the annex. - -It's generally a better idea to use [[git-annex-reinject]](1) instead of -this command. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-reinject]](1) - -[[git-annex-dropkey]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-setpresentkey.mdwn b/doc/git-annex-setpresentkey.mdwn deleted file mode 100644 --- a/doc/git-annex-setpresentkey.mdwn +++ /dev/null @@ -1,44 +0,0 @@ -# NAME - -git-annex setpresentkey - change records of where key is present - -# SYNOPSIS - -git annex setpresentkey `key uuid [1|0]` - -# DESCRIPTION - -This plumbing-level command changes git-annex's records about whether -the specified key's content is present in a remote with the specified uuid. - -Use 1 to indicate the key is present, or 0 to indicate the key is -not present. - -# OPTIONS - -* `--batch` - - Enables batch mode, in which lines are read from stdin. - The line format is "key uuid [1|0]" - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-shell.mdwn b/doc/git-annex-shell.mdwn deleted file mode 100644 --- a/doc/git-annex-shell.mdwn +++ /dev/null @@ -1,194 +0,0 @@ -# NAME - -git-annex-shell - Restricted login shell for git-annex only SSH access - -# SYNOPSIS - -git-annex-shell [-c] command [params ...] - -# DESCRIPTION - -git-annex-shell is a restricted shell, similar to git-shell, which -can be used as a login shell for SSH accounts. - -Since its syntax is identical to git-shell's, it can be used as a drop-in -replacement anywhere git-shell is used. For example it can be used as a -user's restricted login shell. - -# COMMANDS - -Any command not listed below is passed through to git-shell. - -Note that the directory parameter should be an absolute path, otherwise -it is assumed to be relative to the user's home directory. Also the -first "/~/" or "/~user/" is expanded to the specified home directory. - -* configlist directory - - This outputs a subset of the git configuration, in the same form as - `git config --list`. This is used to get the annex.uuid of the remote - repository. - - When run in a repository that does not yet have an annex.uuid, one - will be created, as long as a git-annex branch has already been pushed to - the repository, or if the autoinit=1 flag is used to indicate - initialization is desired. - -* p2pstdio directory uuid - - This causes git-annex-shell to communicate using the git-annex p2p - protocol over stdio. - - The uuid is the one belonging to the repository that will be - communicating with git-annex-shell. - -* notifychanges directory - - This is used by `git-annex remotedaemon` to be notified when - refs in the remote repository are changed. - -* gcryptsetup directory gcryptid - - Sets up a repository as a gcrypt repository. - -* inannex directory [key ...] - - This checks if all specified keys are present in the annex, - and exits zero if so. - - Exits 1 if the key is certainly not present in the annex. - Exits 100 if it's unable to tell (perhaps the key is in the process of - being removed from the annex). - - Used only by the gcrypt special remote. - -* recvkey directory key - - This runs rsync in server mode to receive the content of a key, - and stores the content in the annex. - - Used only by the gcrypt special remote. - -* sendkey directory key - - This runs rsync in server mode to transfer out the content of a key. - - Used only by the gcrypt special remote. - -* dropkey directory [key ...] - - This drops the annexed data for the specified keys. - - Used only by the gcrypt special remote. - -# OPTIONS - -* --uuid=UUID - - git-annex uses this to specify the UUID of the repository it was expecting - git-annex-shell to access, as a sanity check. - -* Also the [[git-annex-common-options]](1) can be used. - -* -- fields=val fields=val.. -- - - Additional fields may be specified this way, to retain compatibility with - past versions of git-annex-shell (that ignore these, but would choke - on new dashed options). - - Currently used fields are autoinit= and remoteuuid= - -# HOOK - -After content is received or dropped from the repository by git-annex-shell, -it runs a hook, `.git/hooks/annex-content` (or `hooks/annex-content` on a bare -repository). The hook is not currently passed any information about what -changed. - -# ENVIRONMENT - -* GIT_ANNEX_SHELL_READONLY - - If set, disallows any action that could modify the git-annex - repository. - - Note that this does not prevent passing commands on to git-shell. - For that, you also need ... - -* GIT_ANNEX_SHELL_LIMITED - - If set, disallows running git-shell to handle unknown commands. - -* GIT_ANNEX_SHELL_APPENDONLY - - If set, allows data to be written to the git-annex repository, - but does not allow data to be removed from it. - - Note that this does not prevent passing commands on to git-shell, - so you will have to separately configure git to reject pushes that - overwrite branches or are otherwise not appends. The git pre-receive - hook may be useful for accomplishing this. - - It's a good idea to enable annex.securehashesonly in a repository - that's set up this way. - -* GIT_ANNEX_SHELL_DIRECTORY - - If set, git-annex-shell will refuse to run commands that do not operate - on the specified directory. - -# EXAMPLES - -To make a `~/.ssh/authorized_keys` file that only allows git-annex-shell -to be run, and not other commands, pass the original command to the -c -option: - - command="git-annex-shell -c \"$SSH_ORIGINAL_COMMAND\"",no-agent-forwarding,no-port-forwarding,no-X11-forwarding ssh-rsa AAAAB3NzaC1y[...] user@example.com - -To further restrict git-annex-shell to a particular repository, -and fully lock it down to read-only mode: - - command="GIT_ANNEX_SHELL_DIRECTORY=/srv/annex GIT_ANNEX_SHELL_LIMITED=true GIT_ANNEX_SHELL_READONLY=true git-annex-shell -c \"$SSH_ORIGINAL_COMMAND\"",restrict ssh-rsa AAAAB3NzaC1y[...] user@example.com - -Obviously, `ssh-rsa AAAAB3NzaC1y[...] user@example.com` needs to -replaced with your SSH key. The above also assumes `git-annex-shell` -is available in your `$PATH`, use an absolute path if it is not the -case. Also note how the above uses the `restrict` option instead of an -explicit list of functionality to disallow. This only works in certain -OpenSSH releases, starting from 7.1p2. - -To only allow adding new objects to the repository, the -`GIT_ANNEX_SHELL_APPENDONLY` variable can be used as well: - - command="GIT_ANNEX_SHELL_DIRECTORY=/srv/annex GIT_ANNEX_SHELL_APPENDONLY=true git-annex-shell -c \"$SSH_ORIGINAL_COMMAND\"",restrict ssh-rsa AAAAB3NzaC1y[...] user@example.com - -This will not keep an attacker from destroying the git history, as -explained above. For this you might want to disallow certain -operations, like branch deletion and force-push, with options from -git-config(1). For example: - - git config receive.denyDeletes true - git config receive.denyNonFastForwards true - -With this configuration, git commits can still remove files, -but they will still be available in the git history and git-annex will -retain their contents. Changes to `git-annex` branch, however, can -negatively impact git-annex's location tracking information and might -cause data loss. To work around this problem, more complex hooks -are required, see for example the `update-paranoid` hook in the git -source distribution. - - -# SEE ALSO - -[[git-annex]](1) - -git-shell(1) - -# AUTHOR - -Joey Hess - - - -Warning: Automatically converted into a man page by mdwn2man. Edit with care diff --git a/doc/git-annex-smudge.mdwn b/doc/git-annex-smudge.mdwn deleted file mode 100644 --- a/doc/git-annex-smudge.mdwn +++ /dev/null @@ -1,66 +0,0 @@ -# NAME - -git-annex smudge - git filter driver for git-annex - -# SYNOPSIS - -git annex smudge [--clean] file - -git annex smudge --update - -# DESCRIPTION - -This command lets git-annex be used as a git filter driver which lets -annexed files in the git repository to be unlocked, instead -of being symlinks, and lets `git add` store files in the annex. - -When adding a file with `git add`, the annex.largefiles config is -consulted to decide if a given file should be added to git as-is, -or if its content are large enough to need to use git-annex. -The annex.gitaddtoannex setting overrides that; setting it to false -prevents `git add` from adding files to the annex. - -However, if git-annex can tell that a file was annexed before, -it will still be added to the annex even when those configs would normally -prevent it. Two examples of this are adding a modified version of an -annexed file, and moving an annexed file to a new filename and adding that. - -The git configuration to use this command as a filter driver is as follows. -This is normally set up for you by git-annex init, so you should -not need to configure it manually. - - [filter "annex"] - smudge = git-annex smudge %f - clean = git-annex smudge --clean %f - -To make git use that filter driver, it needs to be configured in -the `.gitattributes` file or in `.git/info/attributes`. The latter -is normally configured when a repository is initialized, with the following -contents: - - * filter=annex - -The smudge filter does not provide git with the content of annexed files, -because that would be slow and triggers memory leaks in git. Instead, -it records which worktree files need to be updated, and -`git annex smudge --update` later updates the work tree to contain -the content. That is run by several git hooks, including post-checkout -and post-merge. However, a few git commands, notably `git stash` and -`git cherry-pick`, do not run any hooks, so after using those commands -you can manually run `git annex smudge --update` to update the working -tree. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) -[[git-annex-filter-process]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-status.mdwn b/doc/git-annex-status.mdwn deleted file mode 100644 --- a/doc/git-annex-status.mdwn +++ /dev/null @@ -1,46 +0,0 @@ -# NAME - -git-annex status - show the working tree status (deprecated) - -# SYNOPSIS - -git annex status `[path ...]` - -# DESCRIPTION - -Similar to `git status --short`, this command displays the status of the files -in the working tree. - -Show files that are not checked into git (?), deleted (D), -modified (M), added but not committed (A), and type changed/unlocked (T). - -# OPTIONS - -* `--ignore-submodules=when` - - This option is passed on to git status, see its man page for - details. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -git-status(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 deleted file mode 100644 --- a/doc/git-annex-sync.mdwn +++ /dev/null @@ -1,85 +0,0 @@ -# NAME - -git-annex sync - synchronize local repository with remotes - -# SYNOPSIS - -git annex sync `[remote ...]` - -# DESCRIPTION - -This command synchronizes the local repository with its remotes. - -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). - -However, unlike those commands, this command does not transfer annexed -content by default. That will change in a future version of git-annex, - -# OPTIONS - -* `--content`, `--no-content`, `-g` - - The --content option causes the content of annexed files - to also be pulled and pushed. - - The --no-content and -g options cause the content of annexed files to - not be pulled and pushed. - - The `annex.synccontent` configuration can be set to true to make - `--content` be enabled by default. - -* `--content-of=path` `-C path` - - This option causes the content of annexed files in the given - path to also be pulled and pushed. - - This option can be repeated multiple times with different paths. - -* `--commit`, `--no-commit` - - A commit is done by default (unless `annex.autocommit` is set to false). - - Use --no-commit to avoid committing local changes. - -* `--message=msg` `-m msg` - - Use this option to specify a commit message. - -* `--pull`, `--no-pull` - - Use this option to disable pulling. - - When `remote..annex-sync` is set to false, pulling is disabled - for that remote, and using `--pull` will not enable it. - -* `--push`, `--no-push` - - Use this option to disable pushing. - - When `remote..annex-sync` is set to false, pushing is disabled for - that remote, and using `--push` will not enable it. - -* 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-pull]](1) - -[[git-annex-push]](1) - -[[git-annex-assist]](1) - -[[git-annex-satisfy]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-test.mdwn b/doc/git-annex-test.mdwn deleted file mode 100644 --- a/doc/git-annex-test.mdwn +++ /dev/null @@ -1,67 +0,0 @@ -# NAME - -git-annex test - run built-in test suite - -# SYNOPSIS - -git annex test - -# DESCRIPTION - -This runs git-annex's built-in test suite. - -The test suite runs in the `.t` subdirectory of the current directory. - -It can be useful to run the test suite on different filesystems, -or to verify your local installation of git-annex. - -# OPTIONS - -There are several options, provided by Haskell's tasty test -framework. Pass --help for details about those. - -* `--jobs=N` `-JN` - - How many tests to run in parallel. The default is "cpus", which will - runs one job per CPU core. - -* `--keep-failures` - - When there are test failures, leave the `.t` directory populated with - repositories that demonstate the failures, for later analysis. - -* `--test-git-config name=value` - - The test suite prevents git from reading any git configuration files. - Usually it is a good idea to run the test suite with a standard - git configuration. However, this option can be useful to see what - effect a git configuration setting has on the test suite. - - Some configuration settings will break the test suite, in ways that are - due to a bug in git-annex. But it is possible that changing a - configuration can find a legitimate bug in git-annex. - - One valid use of this is to change a git configuration to a value that - is planned to be the new default in a future version of git. - -* `--test-debug` - - Normally output of commands run by the test suite is hidden, so even - when annex.debug or --debug is enabled, it will not be displayed. - This option makes the full output of commands run by the test suite be - displayed. It also makes the test suite run git-annex with --debug. - - It's a good idea to use `-J1` in combinaton with this, otherwise - the output of concurrent tests will be mixed together. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-testremote]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-testremote.mdwn b/doc/git-annex-testremote.mdwn deleted file mode 100644 --- a/doc/git-annex-testremote.mdwn +++ /dev/null @@ -1,58 +0,0 @@ -# NAME - -git-annex testremote - test transfers to/from a remote - -# SYNOPSIS - -git annex testremote `remote` - -# DESCRIPTION - -This tests a remote by sending objects to it, downloading objects from it, -etc. - -It's safe to run in an existing repository (the repository contents are -not altered), although it may perform expensive data transfers. - -It's best to make a new remote for testing purposes. While the test -tries to clean up after itself, if the remote being tested had a bug, -the cleanup might fail, leaving test data in the remote. - -Testing will use the remote's configuration, automatically varying -the chunk sizes, and with simple shared encryption disabled and enabled, -and exporttree disabled and enabled. If the remote is readonly, testing -is limited to checking various properties of downloading from it. - -# OPTIONS - -* `--fast` - - Perform a smaller set of tests. - -* `--test-readonly=file` - - Normally, random objects are generated for the test and are sent to the - remote. When a readonly remote is being tested, that cannot be done, - and so you need to specify some annexed files to use in the testing, - using this option. Their content needs to be present in the readonly remote - being tested, and in the local repository. - - This option can be repeated. - -* `--size=NUnits` - - Tune the base size of generated objects. The default is 1MiB. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-test]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-transferkey.mdwn b/doc/git-annex-transferkey.mdwn deleted file mode 100644 --- a/doc/git-annex-transferkey.mdwn +++ /dev/null @@ -1,39 +0,0 @@ -# NAME - -git-annex transferkey - transfers a key from or to a remote - -# SYNOPSIS - -git annex transferkey `key [--from=remote|--to=remote]` - -# DESCRIPTION - -This plumbing-level command is used to request a single key be -transferred. - -# OPTIONS - -* `--from=remote` - - Download the content of the key from the remote. - -* `--to=remote` - - Upload the content of the key to the remote. - -* `--file=name` - - Provides a hint about the name of the file associated with the key. - (This name is only used in progress displays.) - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-transferkeys.mdwn b/doc/git-annex-transferkeys.mdwn deleted file mode 100644 --- a/doc/git-annex-transferkeys.mdwn +++ /dev/null @@ -1,31 +0,0 @@ -# NAME - -git-annex transferkeys - transfers keys (deprecated) - -# SYNOPSIS - -git annex transferkeys - -# DESCRIPTION - -This plumbing-level command is used to transfer data, by the assistant -in git-annex version 8.20201127 and older. It is still included only -to prevent breakage during upgrades. - -It is a long-running process, which is fed instructions about the keys -to transfer using an internal stdio protocol, which is -intentionally not documented (as it may change at any time). - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-trust.mdwn b/doc/git-annex-trust.mdwn deleted file mode 100644 --- a/doc/git-annex-trust.mdwn +++ /dev/null @@ -1,52 +0,0 @@ -# NAME - -git-annex trust - trust a repository - -# SYNOPSIS - -git annex trust `[repository ...]` - -# DESCRIPTION - -Records that a repository is trusted to not unexpectedly lose -content. Use with care. - -Repositories can be specified using their remote name, their -description, or their UUID. To trust the current repository, use "here". - -Before trusting a repository, consider this scenario. Repository A -is trusted and B is not; both contain the same content. `git-annex drop` -is run on repository A, which checks that B still contains the content, -and so the drop proceeds. Then `git-annex drop` is run on repository B, -which trusts A to still contain the content, so the drop succeeds. Now -the content has been lost. - -# OPTIONS - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-semitrust]](1) - -[[git-annex-untrust]](1) - -[[git-annex-dead]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-unannex.mdwn b/doc/git-annex-unannex.mdwn deleted file mode 100644 --- a/doc/git-annex-unannex.mdwn +++ /dev/null @@ -1,56 +0,0 @@ -# NAME - -git-annex unannex - undo accidental add command - -# SYNOPSIS - -git annex unannex `[path ...]` - -# DESCRIPTION - -Use this to undo an accidental `git annex add` command. It puts the -file back how it was before the add. - -Note that for safety, the content of the file remains in the annex, -until you use `git annex unused` and `git annex dropunused`. - -This is not the command you should use if you intentionally added a -file some time ago, and don't want its contents any more. In that -case you should use `git annex drop` instead, and you can also -`git rm` the file. - -# OPTIONS - -* `--fast` - - Normally this does a slow copy of the file. In `--fast` mode, it - instead makes a hard link from the file to the content in the annex. - But use --fast mode with caution, because editing the file will - change the content in the annex. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* file matching options - - The [[git-annex-matching-options]](1) - can be used to specify files to unannex. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-undo.mdwn b/doc/git-annex-undo.mdwn deleted file mode 100644 --- a/doc/git-annex-undo.mdwn +++ /dev/null @@ -1,49 +0,0 @@ -# NAME - -git-annex undo - undo last change to a file or directory - -# SYNOPSIS - -git annex `[filename|directory] ...` - -# DESCRIPTION - -When passed a filename, undoes the last change that was made to that -file. - -When passed a directory, undoes the last change that was made to the -contents of that directory. - -Running undo a second time will undo the undo, returning the working -tree to the same state it had before. To support undoing an undo of -staged changes, any staged changes are first committed by the -undo command. - -Note that this does not undo get/drop of a file's content; it only -operates on the file tree committed to git. - -# OPTIONS - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* The [[git-annex-common-options]](1) can also be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-add]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-ungroup.mdwn b/doc/git-annex-ungroup.mdwn deleted file mode 100644 --- a/doc/git-annex-ungroup.mdwn +++ /dev/null @@ -1,27 +0,0 @@ -# NAME - -git-annex ungroup - remove a repository from a group - -# SYNOPSIS - -git annex ungroup `repository groupname` - -# DESCRIPTION - -Removes a repository from a group. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-group]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-uninit.mdwn b/doc/git-annex-uninit.mdwn deleted file mode 100644 --- a/doc/git-annex-uninit.mdwn +++ /dev/null @@ -1,41 +0,0 @@ -# NAME - -git-annex uninit - de-initialize git-annex and clean out repository - -# SYNOPSIS - -git annex uninit - -# DESCRIPTION - -Use this to stop using git annex. It will unannex every file in the -repository, and remove all of git-annex's other data, leaving you with a -git repository plus the previously annexed files. - -# OPTIONS - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-unannex]](1) - -[[git-annex-init]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-unlock.mdwn b/doc/git-annex-unlock.mdwn deleted file mode 100644 --- a/doc/git-annex-unlock.mdwn +++ /dev/null @@ -1,79 +0,0 @@ -# NAME - -git-annex unlock - unlock files for modification - -# SYNOPSIS - -git annex unlock `[path ...]` - -# DESCRIPTION - -Normally, the content of annexed files is protected from being changed. -Unlocking an annexed file allows it to be modified. When no files are -specified, all annexed files in the current directory are unlocked. - -Unlocking a file changes how it is stored in the git repository (from a -symlink to a pointer file), so this command will make a change that you -can commit. - -The content of an unlocked file is still stored in git-annex, not git, -and when you commit modifications to the file, the modifications will also -be stored in git-annex, with only the pointer file stored in git. - -If you use `git add` to add a file to the annex, it will be added in unlocked form from -the beginning. This allows workflows where a file starts out unlocked, is -modified as necessary, and is locked once it reaches its final version. - -Normally, unlocking a file requires a copy to be made of its content, so -that its original content is preserved, while the copy can be modified. To -use less space, annex.thin can be set to true; this makes a hard link to -the content be made instead of a copy. (Only when supported by the file -system.) While this can save considerable disk space, any modification made -to a file will cause the old version of the file to be lost from the local -repository. So, enable annex.thin with care. - -# EXAMPLES - - # git annex unlock disk-image - # git commit -m "unlocked to allow VM to make changes as it runs" - - # git annex unlock photo.jpg - # gimp photo.jpg - # git annex add photo.jpg - # git annex lock photo.jpg - # git commit -m "redeye removal" - -# OPTIONS - -* file matching options - - The [[git-annex-matching-options]](1) - can be used to specify files to unlock. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-edit]](1) - -[[git-annex-add]](1) - -[[git-annex-lock]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-unregisterurl.mdwn b/doc/git-annex-unregisterurl.mdwn deleted file mode 100644 --- a/doc/git-annex-unregisterurl.mdwn +++ /dev/null @@ -1,66 +0,0 @@ -# NAME - -git-annex unregisterurl - unregisters an url for a key - -# SYNOPSIS - -git annex unregisterurl `[key url]` - -# DESCRIPTION - -This plumbing-level command can be used to unregister urls when keys can -no longer be downloaded from them. - -Normally the key is a git-annex formatted key. However, if the key cannot be -parsed as a key, and is a valid url, an URL key is constructed from the url. - -Unregistering a key's last web url will make git-annex no longer treat content -as being present in the web special remote. If some other special remote -claims the url, unregistering the url will not update presence information -for it, because the content may still be present on the remote. - -# OPTIONS - -* `--remote=name|uuid` - - Indicate that the url is expected to be claimed by the specified remote. - If some other remote claims the url instead, unregistering it will fail. - - Note that `--remote=web` will prevent any other remote from claiming - the url. - -* `--batch` - - In batch input mode, lines are read from stdin, and each line - should contain a key and url, separated by a single space. - -* `-z` - - When in batch mode, the input is delimited by nulls instead of the usual - newlines. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-registerurl]](1) - -[[git-annex-rmurl]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-untrust.mdwn b/doc/git-annex-untrust.mdwn deleted file mode 100644 --- a/doc/git-annex-untrust.mdwn +++ /dev/null @@ -1,45 +0,0 @@ -# NAME - -git-annex untrust - do not trust a repository - -# SYNOPSIS - -git annex untrust `[repository ...]` - -# DESCRIPTION - -Records that a repository is not trusted and could lose content -at any time. - -Repositories can be specified using their remote name, their -description, or their UUID. To untrust the current repository, use "here". - -# OPTIONS - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-trust]](1) - -[[git-annex-semitrust]](1) - -[[git-annex-dead]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-unused.mdwn b/doc/git-annex-unused.mdwn deleted file mode 100644 --- a/doc/git-annex-unused.mdwn +++ /dev/null @@ -1,108 +0,0 @@ -# NAME - -git-annex unused - look for unused file content - -# SYNOPSIS - -git annex unused - -# DESCRIPTION - -Checks the annex for data that does not correspond to any files present -in any tag or branch, or in the git index, and prints a numbered list -of the data. - -After running this command, you can use the `--unused` option with many -other git-annex commands to operate on all the unused data that was found. - -For example, to move all unused data to origin: - - git annex unused; git annex move --unused --to origin - -# OPTIONS - -* `--fast` - - Only show unused temp and bad files. - -* `--from=repository` - - Check for unused data that is located in a repository. - - The repository should be specified using the name of a configured remote, - or the UUID or description of a repository. - -* `--used-refspec=+ref:-ref` - - By default, any data that the git index uses, or that any refs in the git - repository point to is considered to be used. If you only want to use - some refs, you can use this option to specify the ones to use. Data that - is not in the specified refs (and not used by the index) will then be - considered unused. - - See REFSPEC FORMAT below for details of the format of this setting. - - The git configuration annex.used-refspec can be used to configure - this in a more permanent fashion. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# REFSPEC FORMAT - -The refspec format for --used-refspec and annex.used-refspec is -a colon-separated list of additions and removals of refs. -A somewhat contrived example: - - +refs/heads/*:+HEAD^:+refs/tags/*:-refs/tags/old-tag:reflog - -This adds all refs/heads/ refs, as well as the previous version -of HEAD. It also adds all tags, except for old-tag. And it adds -all refs from the reflog. - -The default behavior is equivilant to `--used-refspec=+refs/*:+HEAD` - -The refspec is processed by starting with an empty set of refs, -and walking the list in order from left to right. - -Each + using a glob is matched against all relevant refs -(a subset of `git show-ref`) and all matching refs are added -to the set. -For example, "+refs/remotes/*" adds all remote refs. - -Each + without a glob adds the literal value to the set. -For example, "+HEAD^" adds "HEAD^". - -Each - is matched against the set of refs accumulated so far. -Any refs with names that match are removed from the set. - -"reflog" adds all the refs from the reflog. This will make past versions -of files not be considered to be unused until the ref expires from the -reflog (by default for 90 days). Note that this may make git-annex unused -take some time to complete, it if needs to check every ref from the -reflog. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-dropunused]](1) - -[[git-annex-addunused]](1) - -[[git-annex-whereused]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-upgrade.mdwn b/doc/git-annex-upgrade.mdwn deleted file mode 100644 --- a/doc/git-annex-upgrade.mdwn +++ /dev/null @@ -1,60 +0,0 @@ -# NAME - -git-annex upgrade - upgrade repository - -# SYNOPSIS - -git annex upgrade - -# DESCRIPTION - -Upgrades the repository to the latest version. - -Each git-annex repository has an annex.version in its git configuration, -that indicates the repository version. When an old repository version -becomes deprecated, git-annex will automatically upgrade it -(unless annex.autoupgraderepository is set to false). To manually upgrade, -you can use this command. - -Sometimes there's a newer repository version that is not the default yet, -and then you can use this command to upgrade to it. - -Currently, git-annex supports upgrades all the way back to version 0, which -was only used by its author. It's expected that git-annex will always -support upgrading from all past repository versions -- this is necessary to -allow archives to be taken offline for years and later used. - -# OPTIONS - -* --autoonly - - Only do whatever automatic upgrade can be done, don't necessarily - upgrade to the latest version. This is used internally by git-annex. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-migrate]](1) - -Upgrades procedures and history: - -News and release notes: - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-vadd.mdwn b/doc/git-annex-vadd.mdwn deleted file mode 100644 --- a/doc/git-annex-vadd.mdwn +++ /dev/null @@ -1,42 +0,0 @@ -# NAME - -git-annex vadd - add subdirs to current view - -# SYNOPSIS - -git annex vadd `[field=glob ...] [field=value ...] [tag ...] [?tag ...] [field?=glob]` - -# DESCRIPTION - -Changes the current view, adding an additional level of directories -to categorize the files. - -For example, when the view is by author/tag, `vadd year=*` will -change it to year/author/tag. - -So will `vadd year=2014 year=2013`, but limiting the years in view -to only those two. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-metadata]](1) - -[[git-annex-view]](1) - -[[git-annex-vpop]](1) - -[[git-annex-vfilter]](1) - -[[git-annex-vcycle]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-vcycle.mdwn b/doc/git-annex-vcycle.mdwn deleted file mode 100644 --- a/doc/git-annex-vcycle.mdwn +++ /dev/null @@ -1,38 +0,0 @@ -# NAME - -git-annex vcycle - switch view to next layout - -# SYNOPSIS - -git annex vcycle - -# DESCRIPTION - -When a view involves nested subdirectories, this cycles the order. - -For example, when the view is by year/author/tag, `vcycle` will switch -it to author/tag/year. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-metadata]](1) - -[[git-annex-view]](1) - -[[git-annex-vpop]](1) - -[[git-annex-vadd]](1) - -[[git-annex-vfilter]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-version.mdwn b/doc/git-annex-version.mdwn deleted file mode 100644 --- a/doc/git-annex-version.mdwn +++ /dev/null @@ -1,38 +0,0 @@ -# NAME - -git-annex version - show version info - -# SYNOPSIS - -git annex version - -# DESCRIPTION - -Shows the version of git-annex, as well as repository version information. - -git-annex's version is in the form MAJOR.DATE, where MAJOR is a number -like 5, which corresponds to the current repository version, and DATE -is the date of the last release, like 20150320. - -Daily builds of git-annex will append a "-gREF" to the version, which -corresponds to the git ref from git-annex's source repository that was -built. Therefore, "5.20150320-gdd35cf3" is a daily build, and -"5.20150401" is an April 1st release made a bit later. - -# OPTIONS - -* `--raw` - - Causes only git-annex's version to be output, and nothing else. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-vfilter.mdwn b/doc/git-annex-vfilter.mdwn deleted file mode 100644 --- a/doc/git-annex-vfilter.mdwn +++ /dev/null @@ -1,36 +0,0 @@ -# NAME - -git-annex vfilter - filter current view - -# SYNOPSIS - -git annex vfilter `[tag ...] [field=value ...] [?tag ...] [field?=glob] [!tag ...] [field!=value ...]` - -# DESCRIPTION - -Filters the current view to only the files that have the -specified field values and tags. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-metadata]](1) - -[[git-annex-view]](1) - -[[git-annex-vpop]](1) - -[[git-annex-vadd]](1) - -[[git-annex-vcycle]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-vicfg.mdwn b/doc/git-annex-vicfg.mdwn deleted file mode 100644 --- a/doc/git-annex-vicfg.mdwn +++ /dev/null @@ -1,32 +0,0 @@ -# NAME - -git-annex vicfg - edit configuration in git-annex branch - -# SYNOPSIS - -git annex vicfg - -# DESCRIPTION - -Opens EDITOR on a temp file containing all of git-annex's -configuration settings that are stored in the git-annex branch, -and when it exits, stores any changes made back to the git-annex branch. - -Unlike git config settings, these configuration settings can be seen -by all clones of the repository. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -git-config(1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-view.mdwn b/doc/git-annex-view.mdwn deleted file mode 100644 --- a/doc/git-annex-view.mdwn +++ /dev/null @@ -1,77 +0,0 @@ -# NAME - -git-annex view - enter a view branch - -# SYNOPSIS - -git annex view `[tag ...] [field=value ...] [field=glob ...] [?tag ...] [field?=glob] [!tag ...] [field!=value ...]` - -# DESCRIPTION - -Uses metadata to build a view branch of the files in the current branch, -and checks out the view branch. Only files in the current branch whose -metadata matches all the specified field values and tags will be -shown in the view. - -Multiple values for a metadata field can be specified, either by using -a glob (`field="*"`) or by listing each wanted value. The resulting view -will put files in subdirectories according to the value of their fields. - -Once within such a view, you can make additional directories, and -copy or move files into them. When you commit, the metadata will -be updated to correspond to your changes. Deleting files and committing -also updates the metadata. - -As well as the usual metadata, there are fields available corresponding -to the path to the file. So a file "foo/bar/baz/file" has fields "/=foo", -"foo/=bar", and "foo/bar/=baz". These location fields can be used the -same as other metadata to construct the view. - -For example, `/=foo` will only include files from the foo -directory in the view, while `foo/=*` will preserve the -subdirectories of the foo directory in the view. - -To enter a view containing only files that lack a given metadata -value or tag, specify field!=value or !tag. (Globs cannot be used here.) - -`field?=*` is like `field=*` but adds an additional directory named `_` (by -default) that contains files that do not have the field set to any value. -Similarly, `?tag` adds an additional directory named `_` that contains -files that do not have any tags set. Moving files from the `_` directory to -another directory and committing will set the metadata. And moving files -into the `_` directory and committing will unset the metadata. - -The name of the `_` directory can be changed using the annex.viewunsetdirectory -git config. - -Filenames in the view branch include their path within the original branch, to -ensure that they are unique. The path comes after the main filename, and -before any extensions. For example, "foo/bar.baz" will have a name -like "bar_%foo%.baz". annex.maxextensionlength can be used to configure -what is treated as an extension. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-metadata]](1) - -[[git-annex-vpop]](1) - -[[git-annex-vfilter]](1) - -[[git-annex-vadd]](1) - -[[git-annex-vcycle]](1) - -[[git-annex-adjust]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-vpop.mdwn b/doc/git-annex-vpop.mdwn deleted file mode 100644 --- a/doc/git-annex-vpop.mdwn +++ /dev/null @@ -1,38 +0,0 @@ -# NAME - -git-annex vpop - switch back to previous view - -# SYNOPSIS - -git annex vpop `[N]` - -# DESCRIPTION - -Switches from the currently active view back to the previous view. -Or, from the first view back to original branch. - -The optional number tells how many views to pop. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-metadata]](1) - -[[git-annex-view]](1) - -[[git-annex-vfilter]](1) - -[[git-annex-vadd]](1) - -[[git-annex-vcycle]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-wanted.mdwn b/doc/git-annex-wanted.mdwn deleted file mode 100644 --- a/doc/git-annex-wanted.mdwn +++ /dev/null @@ -1,39 +0,0 @@ -# NAME - -git-annex wanted - get or set preferred content expression - -# SYNOPSIS - -git annex wanted `repository [expression]` - -# DESCRIPTION - -When run with an expression, configures the content that is preferred -to be held in the archive. See [[git-annex-preferred-content]](1) - -For example: - - git annex wanted . "include=*.mp3 or include=*.ogg" - -Without an expression, displays the current preferred content setting -of the repository. - -# OPTIONS - -* The [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-required]](1) - -[[git-annex-preferred-content]](1) - -[[git-annex-groupwanted]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-watch.mdwn b/doc/git-annex-watch.mdwn deleted file mode 100644 --- a/doc/git-annex-watch.mdwn +++ /dev/null @@ -1,47 +0,0 @@ -# NAME - -git-annex watch - daemon to watch for changes - -# SYNOPSIS - -git annex watch - -# DESCRIPTION - -Watches for changes to files in the current directory and its subdirectories, -and takes care of automatically adding new files, as well as dealing with -deleted, copied, and moved files. With this running as a daemon in the -background, you no longer need to manually run git commands when -manipulating your files. - -By default, all new files in the directory will be added to the repository. -(Including dotfiles.) To block some files from being added, use -`.gitignore` files. - -By default, all files that are added are added to the annex, the same -as when you run `git annex add`. If you configure annex.largefiles, -files that it does not match will instead be added with `git add`. - -# OPTIONS - -* `--foreground` - - Avoid forking to the background. - -* `--stop` - - Stop a running daemon in the current repository. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-assistant]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-webapp.mdwn b/doc/git-annex-webapp.mdwn deleted file mode 100644 --- a/doc/git-annex-webapp.mdwn +++ /dev/null @@ -1,53 +0,0 @@ -# NAME - -git-annex webapp - launch webapp - -# SYNOPSIS - -git annex webapp - -# DESCRIPTION - -Opens a web app, that allows easy setup of a git-annex repository, -and control of the git-annex assistant. If the assistant is not -already running, it will be started. - -By default, the webapp can only be accessed from localhost, and running -it opens a browser window. - -# OPTIONS - -* `--listen=address` - - Useful for using the webapp on a remote computer. This makes the webapp - listen on the specified address. - - This disables running a local web browser, and outputs the url you - can use to open the webapp. - - Set annex.listen in the git config to make the webapp always - listen on an address. - -* Also the [[git-annex-common-options]](1) can be used. - -# USING HTTPS - -When using the webapp on a remote computer, you'll almost certainly -want to enable HTTPS. The webapp will use HTTPS if it finds -a .git/annex/privkey.pem and .git/annex/certificate.pem. Here's -one way to generate those files, using a self-signed certificate: - - openssl genrsa -out .git/annex/privkey.pem 4096 - openssl req -new -x509 -key .git/annex/privkey.pem > .git/annex/certificate.pem - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-assistant]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-whereis.mdwn b/doc/git-annex-whereis.mdwn deleted file mode 100644 --- a/doc/git-annex-whereis.mdwn +++ /dev/null @@ -1,122 +0,0 @@ -# NAME - -git-annex whereis - lists repositories that have file content - -# SYNOPSIS - -git annex whereis `[path ...]` - -# DESCRIPTION - -Displays information about where the contents of files are located. - -For example: - - # git annex whereis - whereis my_cool_big_file (1 copy) - 0c443de8-e644-11df-acbf-f7cd7ca6210d -- laptop - whereis other_file (3 copies) - 0c443de8-e644-11df-acbf-f7cd7ca6210d -- laptop - 62b39bbe-4149-11e0-af01-bb89245a1e61 -- usb drive [here] - 7570b02e-15e9-11e0-adf0-9f3f94cb2eaa -- backup drive - -Note that this command does not contact remotes to verify if they still -have the content of files. It only reports on the last information that was -received from remotes. - -# OPTIONS - -* matching options - - The [[git-annex-matching-options]](1) - can be used to control what to act on. - -* `--key=keyname` - - Show where a particular git-annex key is located. - -* `--all` `-A` - - Show whereis information for all known keys. - - (Except for keys that have been marked as dead, - see [[git-annex-dead]](1).) - -* `--branch=ref` - - Show whereis information for files in the specified branch or treeish. - -* `--unused` - - Show whereis information for files found by last run of git-annex unused. - -* `--batch` - - Enables batch mode, in which a file is read in a line from stdin, - its information displayed, and repeat. - - Note that if the file is not an annexed file, or does not match - specified matching options, an empty line will be - output instead. - -* `--batch-keys` - - This is like `--batch` but the lines read from stdin are parsed as keys. - -* `-z` - - Makes batch input be delimited by nulls instead of the usual - newlines. - -* `--json` - - Enable JSON output. This is intended to be parsed by programs that use - git-annex. Each line of output is a JSON object. - -* `--json-error-messages` - - Messages that would normally be output to standard error are included in - the JSON instead. - -* `--format=value` - - Use custom output formatting. - - The value is a format string, in which '${var}' is expanded to the - value of a variable. To right-justify a variable with whitespace, - use '${var;width}' ; to left-justify a variable, use '${var;-width}'; - to escape unusual characters (including control characters) - in a variable, use '${escaped_var}' - - These variables are available for use in formats: file, key, uuid, - url, backend, bytesize, humansize, keyname, hashdirlower, hashdirmixed, - mtime (for the mtime field of a WORM key). - - Also, '\\n' is a newline, '\\000' is a NULL, etc. - - When the format contains the uuid variable, it will be expanded in turn - for each repository that contains the file content. For example, - with --format="${file} ${uuid}\\n", output will look like: - - foo 00000000-0000-0000-0000-000000000001 - foo a7f7ddd0-9a08-11ea-ab66-8358e4209d30 - bar a7f7ddd0-9a08-11ea-ab66-8358e4209d30 - - The same applies when the url variable is used and a file has multiple - recorded urls. - -* Also the [[git-annex-common-options]](1) can be used. - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-find]](1) - -[[git-annex-list]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-whereused.mdwn b/doc/git-annex-whereused.mdwn deleted file mode 100644 --- a/doc/git-annex-whereused.mdwn +++ /dev/null @@ -1,53 +0,0 @@ -# NAME - -git-annex whereused - find what files use or used a key - -# SYNOPSIS - -git annex whereused `--key=keyname|--unused` - -# DESCRIPTION - -Finds what files use or used a key. - -For each file in the working tree that uses a key, this outputs one line, -starting with the key, then a space, and then the name of the file. -When multiple files use the same key, they will all be listed. When -nothing is found that uses the key, there will be no output. - -The default is to find only files in the current working tree that use a -key. The `--historical` option makes it also find past versions of files. - -# OPTIONS - -* `--key=keyname` - - Operate on this key. - -* `--unused` - - Operate on keys found by last run of git-annex unused. - - Usually these keys won't be used by any files in the current working - tree, or any tags or branches. Combining this option with `--historical` - will find past uses of the keys. - -* `--historical` - - When no files in the current working tree use a key, this causes more - work to be done, looking at past versions of the current branch, other - branches, tags, and the reflog, to find somewhere that the key was used. - It stops after finding one use of the key, and outputs a git rev that - refers to where it was used, eg "HEAD@{40}:somefile" - -# SEE ALSO - -[[git-annex]](1) - -[[git-annex-unused]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn deleted file mode 100644 --- a/doc/git-annex.mdwn +++ /dev/null @@ -1,2103 +0,0 @@ -# NAME - -git-annex - manage files with git, without checking their contents in - -# SYNOPSIS - -git annex command [params ...] - -# DESCRIPTION - -git-annex allows managing files with git, without checking the file -contents into git. While that may seem paradoxical, it is useful when -dealing with files larger than git can currently easily handle, whether due -to limitations in memory, checksumming time, or disk space. - -Even without file content tracking, being able to manage files with git, -move files around and delete files with versioned directory trees, and use -branches and distributed clones, are all very handy reasons to use git. And -annexed files can co-exist in the same git repository with regularly -versioned files, which is convenient for maintaining documents, Makefiles, -etc that are associated with annexed files but that benefit from full -revision control. - -When a file is annexed, its content is moved into a key-value store, and -a symlink is made that points to the content. These symlinks are checked into -git and versioned like regular files. You can move them around, delete -them, and so on. Pushing to another git repository will make git-annex -there aware of the annexed file, and it can be used to retrieve its -content from the key-value store. - -# EXAMPLES - - # git annex get video/hackity_hack_and_kaxxt.mov - get video/hackity_hack_and_kaxxt.mov (not available) - I was unable to access these remotes: server - Try making some of these repositories available: - 5863d8c0-d9a9-11df-adb2-af51e6559a49 -- my home file server - 58d84e8a-d9ae-11df-a1aa-ab9aa8c00826 -- portable USB drive - ca20064c-dbb5-11df-b2fe-002170d25c55 -- backup SATA drive - failed - # sudo mount /media/usb - # git remote add usbdrive /media/usb - # git annex get video/hackity_hack_and_kaxxt.mov - get video/hackity_hack_and_kaxxt.mov (from usbdrive...) ok - - # git annex add iso - add iso/Debian_5.0.iso ok - - # git annex drop iso/Debian_4.0.iso - drop iso/Debian_4.0.iso ok - - # git annex move iso --to=usbdrive - move iso/Debian_5.0.iso (moving to usbdrive...) ok - -# COMMONLY USED COMMANDS - -* `help` - - Display built-in help. - - For help on a specific command, use `git annex help command` - -* `add [path ...]` - - Adds files to the annex. - - See [[git-annex-add]](1) for details. - -* `get [path ...]` - - Makes the content of annexed files available in this repository. - - See [[git-annex-get]](1) for details. - -* `drop [path ...]` - - Drops the content of annexed files from this repository. - - See [[git-annex-drop]](1) for details. - -* `move [path ...] [--from=remote|--to=remote]` - - Moves the content of files from or to another remote. - - See [[git-annex-move]](1) for details. - -* `copy [path ...] [--from=remote|--to=remote]` - - Copies the content of files from or to another remote. - - See [[git-annex-copy]](1) for details. - -* `status [path ...]` - - Show the working tree status. (deprecated) - - See [[git-annex-status]](1) for details. - -* `unlock [path ...]` - - Unlock annexed files for modification. - - See [[git-annex-unlock]](1) for details. - -* `edit [path ...]` - - This is an alias for the unlock command. May be easier to remember, - if you think of this as allowing you to edit an annexed file. - -* `lock [path ...]` - - Use this to undo an unlock command if you don't want to modify - the files, or have made modifications you want to discard. - - 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. - - See [[git-annex-sync]](1) for details. - -* `assist [remote ...]` - - Add files and sync changes with remotes. - - See [[git-annex-assist]](1) for details. - -* `satisfy [remote ...]` - - Satisfy preferred content settings by transferring and dropping content. - - See [[git-annex-satisfy]](1) for details. - -* `mirror [path ...] [--to=remote|--from=remote]` - - Mirror content of files to/from another repository. - - See [[git-annex-mirror]](1) for details. - -* `addurl [url ...]` - - Downloads each url to its own file, which is added to the annex. - - See [[git-annex-addurl]](1) for details. - -* `rmurl file url` - - Record that the file is no longer available at the url. - - See [[git-annex-rmurl]](1) for details. - -* `import --from remote branch[:subdir] | [path ...]` - - Add a tree of files to the repository. - - See [[git-annex-import]](1) for details. - -* `importfeed [url ...]` - - Imports the contents of podcast feeds into the annex. - - See [[git-annex-importfeed]](1) for details. - -* `export treeish --to remote` - - Export content to a remote. - - See [[git-annex-export]](1) for details. - -* `undo [filename|directory] ...` - - Undo last change to a file or directory. - - See [[git-annex-undo]](1) for details. - -* `multicast` - - Multicast file distribution. - - See [[git-annex-multicast]](1) for details. - -* `watch` - - Daemon to watch for changes and autocommit. - - See [[git-annex-watch]](1) for details. - -* `assistant` - - Daemon to automatically sync changes. - - See [[git-annex-assistant]](1) for details. - -* `webapp` - - Opens a web app, that allows easy setup of a git-annex repository, - and control of the git-annex assistant. If the assistant is not - already running, it will be started. - - See [[git-annex-webapp]](1) for details. - -* `remotedaemon` - - Persistant communication with remotes. - - See [[git-annex-remotedaemon]](1) for details. - -# REPOSITORY SETUP COMMANDS - -* `init [description]` - - Until a repository (or one of its remotes) has been initialized, - git-annex will refuse to operate on it, to avoid accidentally - using it in a repository that was not intended to have an annex. - - See [[git-annex-init]](1) for details. - -* `describe repository description` - - Changes the description of a repository. - - See [[git-annex-describe]](1) for details. - -* `initremote name type=value [param=value ...]` - - Creates a new special remote, and adds it to `.git/config`. - - See [[git-annex-initremote]](1) for details. - -* `enableremote name [param=value ...]` - - Enables use of an existing special remote in the current repository. - - See [[git-annex-enableremote]](1) for details. - -* `configremote name [param=value ...]` - - Changes configuration of an existing special remote. - - See [[git-annex-configremote]](1) for details. - - -* `renameremote` - - Renames a special remote. - - See [[git-annex-renameremote]](1) for details. - -* `enable-tor` - - Sets up tor hidden service. - - See [[git-annex-enable-tor]](1) for details. - -* `numcopies [N]` - - Configure desired number of copies. - - See [[git-annex-numcopies]](1) for details. - -* `mincopies [N]` - - Configure minimum number of copies. - - See [[git-annex-mincopies]](1) for details. - -* `trust [repository ...]` - - Records that a repository is trusted to not unexpectedly lose - content. Use with care. - - See [[git-annex-trust]](1) for details. - -* `untrust [repository ...]` - - Records that a repository is not trusted and could lose content - at any time. - - See [[git-annex-untrust]](1) for details. - -* `semitrust [repository ...]` - - Returns a repository to the default semi trusted state. - - See [[git-annex-semitrust]](1) for details. - -* `group repository groupname` - - Add a repository to a group. - - See [[git-annex-group]](1) for details. - -* `ungroup repository groupname` - - Removes a repository from a group. - - See [[git-annex-ungroup]](1) for details. - -* `wanted repository [expression]` - - Get or set preferred content expression. - - See [[git-annex-wanted]](1) for details. - -* `groupwanted groupname [expression]` - - Get or set groupwanted expression. - - See [[git-annex-groupwanted]](1) for details. - -* `required repository [expression]` - - Get or set required content expression. - - See [[git-annex-required]](1) for details. - -* `schedule repository [expression]` - - Get or set scheduled jobs. - - See [[git-annex-schedule]](1) for details. - -* `config` - - Get and set other configuration stored in git-annex branch. - - See [[git-annex-config]](1) for details. - -* `vicfg` - - Opens EDITOR on a temp file containing most of the above configuration - settings, as well as a few others, and when it exits, stores any changes - made back to the git-annex branch. - - See [[git-annex-vicfg]](1) for details. - -* `adjust` - - Switches a repository to use an adjusted branch, which can automatically - unlock all files, etc. - - See [[git-annex-adjust]](1) for details. - -* `direct` - - Switches a repository to use direct mode. (deprecated) - - See [[git-annex-direct]](1) for details. - -* `indirect` - - Switches a repository to use indirect mode. (deprecated) - - See [[git-annex-indirect]](1) for details. - -# REPOSITORY MAINTENANCE COMMANDS - -* `fsck [path ...]` - - Checks the annex consistency, and warns about or fixes any problems found. - This is a good complement to `git fsck`. - - See [[git-annex-fsck]](1) for details. - -* `expire [repository:]time ...` - - Expires repositories that have not recently performed an activity - (such as a fsck). - - See [[git-annex-expire]](1) for details. - -* `unused` - - Checks the annex for data that does not correspond to any files present - in any tag or branch, and prints a numbered list of the data. - - See [[git-annex-unused]](1) for details. - -* `dropunused [number|range ...]` - - Drops the data corresponding to the numbers, as listed by the last - `git annex unused` - - See [[git-annex-dropunused]](1) for details. - -* `addunused [number|range ...]` - - Adds back files for the content corresponding to the numbers or ranges, - as listed by the last `git annex unused`. - - See [[git-annex-addunused]](1) for details. - -* `fix [path ...]` - - Fixes up symlinks that have become broken to again point to annexed content. - - See [[git-annex-fix]](1) for details. - -* `merge` - - Automatically merge changes from remotes. - - See [[git-annex-merge]](1) for details. - -* `upgrade` - - Upgrades the repository. - - See [[git-annex-upgrade]](1) for details. - -* `dead [repository ...] [--key key]` - - Indicates that a repository or a single key has been irretrievably lost. - - See [[git-annex-dead]](1) for details. - -* `forget` - - Causes the git-annex branch to be rewritten, throwing away historical - data about past locations of files. - - See [[git-annex-forget]](1) for details. - -* `filter-branch` - - Produces a filtered version of the git-annex branch. - - See [[git-annex-filter-branch]](1) for details. - -* `repair` - - This can repair many of the problems with git repositories that `git fsck` - detects, but does not itself fix. It's useful if a repository has become - badly damaged. One way this can happen is if a repository used by git-annex - is on a removable drive that gets unplugged at the wrong time. - - See [[git-annex-repair]](1) for details. - -* `p2p` - - Configure peer-2-Peer links between repositories. - - See [[git-annex-p2p]](1) for details. - -# QUERY COMMANDS - -* `find [path ...]` - - Outputs a list of annexed files in the specified path. With no path, - finds files in the current directory and its subdirectories. - - See [[git-annex-find]](1) for details. - -* `whereis [path ...]` - - Displays information about where the contents of files are located. - - See [[git-annex-whereis]](1) for details. - -* `list [path ...]` - - Displays a table of remotes that contain the contents of the specified - files. This is similar to whereis but a more compact display. - - See [[git-annex-list]](1) for details. - -* `whereused` - - Finds what files use or used a key. - -* `log [path ...]` - - Displays the location log for the specified file or files, - showing each repository they were added to ("+") and removed from ("-"). - - See [[git-annex-log]](1) for details. - -* `info [directory|file|remote|uuid ...]` - - Displays statistics and other information for the specified item, - which can be a directory, or a file, or a remote, or the uuid of a - repository. - - When no item is specified, displays statistics and information - for the repository as a whole. - - See [[git-annex-info]](1) for details. - -* `version` - - Shows the version of git-annex, as well as repository version information. - - See [[git-annex-version]](1) for details. - -* `map` - - Generate map of repositories. - - See [[git-annex-map]](1) for details. - -* `inprogress` - - Access files while they're being downloaded. - - See [[git-annex-inprogress]](1) for details. - -* `findkeys` - - Similar to `git-annex find`, but operating on keys. - - See [[git-annex-findkeys]](1) for details. - -# METADATA COMMANDS - -* `metadata [path ...]` - - The content of an annexed file can have any number of metadata fields - attached to it to describe it. Each metadata field can in turn - have any number of values. - - This command can be used to set metadata, or show the currently set - metadata. - - See [[git-annex-metadata]](1) for details. - -* `view [tag ...] [field=value ...] [field=glob ...] [?tag ...] [field?=glob] [!tag ...] [field!=value ...]` - - Uses metadata to build a view branch of the files in the current branch, - and checks out the view branch. Only files in the current branch whose - metadata matches all the specified field values and tags will be - shown in the view. - - See [[git-annex-view]](1) for details. - -* `vpop [N]` - - Switches from the currently active view back to the previous view. - Or, from the first view back to original branch. - - See [[git-annex-vpop]](1) for details. - -* `vfilter [tag ...] [field=value ...] [!tag ...] [field!=value ...]` - - Filters the current view to only the files that have the - specified field values and tags. - - See [[git-annex-vfilter]](1) for details. - -* `vadd [field=glob ...] [field=value ...] [tag ...]` - - Changes the current view, adding an additional level of directories - to categorize the files. - - See [[git-annex-vfilter]](1) for details. - -* `vcycle` - - When a view involves nested subdirectories, this cycles the order. - - See [[git-annex-vcycle]](1) for details. - -# UTILITY COMMANDS - -* `migrate [path ...]` - - Changes the specified annexed files to use a different key-value backend. - - See [[git-annex-migrate]](1) for details. - -* `reinject src dest` - - Moves the src file into the annex as the content of the dest file. - This can be useful if you have obtained the content of a file from - elsewhere and want to put it in the local annex. - - See [[git-annex-reinject]](1) for details. - -* `unannex [path ...]` - - Use this to undo an accidental `git annex add` command. It puts the - file back how it was before the add. - - See [[git-annex-unannex]](1) for details. - -* `uninit` - - De-initialize git-annex and clean out repository. - - See [[git-annex-uninit]](1) for details. - -* `reinit uuid|description` - - Initialize repository, reusing old UUID. - - See [[git-annex-reinit]](1) for details. - -# PLUMBING COMMANDS - -* `pre-commit [path ...]` - - This is meant to be called from git's pre-commit hook. `git annex init` - automatically creates a pre-commit hook using this. - - See [[git-annex-pre-commit]](1) for details. - -* `post-receive` - - This is meant to be called from git's post-receive hook. `git annex init` - automatically creates a post-receive hook using this. - - See [[git-annex-post-receive]](1) for details. - -* `lookupkey [file ...]` - - Looks up key used for file. - - See [[git-annex-lookupkey]](1) for details. - -* `calckey [file ...]` - - Calculates the key that would be used to refer to a file. - - See [[git-annex-calckey]](1) for details. - -* `contentlocation [key ..]` - - Looks up location of annexed content for a key. - - See [[git-annex-contentlocation]](1) for details. - -* `examinekey [key ...]` - - Print information that can be determined purely by looking at the key. - - See [[git-annex-examinekey]](1) for details. - -* `matchexpression` - - Checks if a preferred content expression matches provided data. - - See [[git-annex-matchexpression]](1) for details. - -* `fromkey [key file]` - - Manually set up a file in the git repository to link to a specified key. - - See [[git-annex-fromkey]](1) for details. - -* `registerurl [key url]` - - Registers an url for a key. - - See [[git-annex-registerurl]](1) for details. - -* `unregisterurl [key url]` - - Unregisters an url for a key. - - See [[git-annex-unregisterurl]](1) for details. - -* `setkey key file` - - Moves a file into the annex as the content of a key. - - See [[git-annex-setkey]](1) for details. - -* `dropkey [key ...]` - - Drops annexed content for specified keys. - - See [[git-annex-dropkey]](1) for details. - -* `transferkey key [--from=remote|--to=remote]` - - Transfers a key from or to a remote. - - See [[git-annex-transferkey]](1) for details. - -* `transferrer` - - Used internally by git-annex to transfer content. - - See [[git-annex-transferrer]](1) for details. - -* `transferkeys` - - Used internally by old versions of the assistant. - - See [[git-annex-transferkey]](1) for details. - -* `setpresentkey key uuid [1|0]` - - This plumbing-level command changes git-annex's records about whether - the specified key's content is present in a remote with the specified uuid. - - See [[git-annex-setpresentkey]](1) for details. - -* `readpresentkey key uuid` - - Read records of where key is present. - - See [[git-annex-readpresentkey]](1) for details. - -* `checkpresentkey key remote` - - Check if key is present in remote. - - See [[git-annex-checkpresentkey]](1) for details. - -* `rekey [file key ...]` - - Change keys used for files. - - See [[git-annex-rekey]](1) for details. - -* `resolvemerge` - - 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 pull` - or `git annex merge`. - - See [[git-annex-resolvemerge]](1) for details. - -* `diffdriver` - - This can be used to make `git diff` diff the content of annexed files. - - See [[git-annex-diffdriver]](1) for details. - -* `smudge` - - This command lets git-annex be used as a git filter driver, allowing - annexed files in the git repository to be unlocked regular files instead - of symlinks. - - See [[git-annex-smudge]](1) for details. - -* `filter-process` - - An alternative implementation of a git filter driver, that is faster - in some situations and slower in others than `git-annex smudge`. - - See [[git-annex-filter-process]](1) for details. - -* `restage` - - Restages unlocked files in the git index. - - See [[git-annex-restage]](1) for details. - -* `findref [ref]` - - Lists files in a git ref. (deprecated) - - See [[git-annex-findref]](1) for details. - -* `proxy -- git cmd [options]` - - Bypass direct mode guard. (deprecated) - - See [[git-annex-proxy]](1) for details. - -# TESTING COMMANDS - -* `test` - - This runs git-annex's built-in test suite. - - See [[git-annex-test]](1) for details. - -* `testremote remote` - - This tests a remote by generating some random objects and sending them to - the remote, then redownloading them, removing them from the remote, etc. - - It's safe to run in an existing repository (the repository contents are - not altered), although it may perform expensive data transfers. - - See [[git-annex-testremote]](1) for details. - -* `fuzztest` - - Generates random changes to files in the current repository, - for use in testing the assistant. - - See [[git-annex-fuzztest]](1) for details. - -* `benchmark` - - This runs git-annex's built-in benchmarks, if it was built with - benchmarking support. - - See [[git-annex-benchmark]](1) for details. - -# ADDON COMMANDS - -In addition to all the commands listed above, more commands can be added to -git-annex by dropping commands named like "git-annex-foo" into a directory -in the PATH. - -# CONFIGURATION - -Like other git commands, git-annex is configured via `.git/config`. -These settings, as well as relevant git config settings, are -the ones git-annex uses. - -(Some of these settings can also be set, across all clones of the -repository, using [[git-annex-config]]. See its man page for a list.) - -* `annex.uuid` - - A unique UUID for this repository (automatically set). - -* `annex.backend` - - Name of the default key-value backend to use when adding new files - to the repository. See [[git-annex-backends]](1) for information about - available backends. - - This is overridden by annex annex.backend configuration in the - .gitattributes files, and by the --backend option. - - (This used to be named `annex.backends`, and that will still be used - if set.) - -* `annex.securehashesonly` - - Set to true to indicate that the repository should only use - cryptographically secure hashes (SHA2, SHA3) and not insecure - hashes (MD5, SHA1) for content. - - When this is set, the contents of files using cryptographically - insecure hashes will not be allowed to be added to the repository. - - Also, `git-annex fsck` will complain about any files present in - the repository that use insecure hashes. And, - `git-annex import --no-content` will refuse to import files - from special remotes using insecure hashes. - - To configure the behavior in new clones of the repository, - this can be set using [[git-annex-config]]. - -* `annex.maxextensionlength` - - Maximum length, in bytes, of what is considered a filename extension. - This is used when adding a file to a backend that preserves filename extensions, - and also when generating a view branch. - - The default length is 4, which allows extensions like "jpeg". The dot before - the extension is not counted part of its length. At most two extensions - at the end of a filename will be preserved, e.g. .gz or .tar.gz . - -* `annex.diskreserve` - - Amount of disk space to reserve. Disk space is checked when transferring - annexed content to avoid running out, and additional free space can be - reserved via this option, to make space for other data (such as git - commit logs). Can be specified with any commonly used units, for - example, "0.5 gb", "500M", or "100 KiloBytes" - - The default reserve is 100 megabytes. - -* `annex.skipunknown` - - Set to true to make commands like "git-annex get" silently skip over - items that are listed in the command line, but are not checked into git. - - Set to false to make it an error for commands like "git-annex get" - to be asked to operate on files that are not checked into git. - (This is the default in recent versions of git-annex.) - - Note that, when annex.skipunknown is false, a command like "git-annex get ." - will fail if no files in the current directory are checked into git, - but a command like "git-annex get" will not fail, because the current - directory is not listed, but is implicit. Commands like "git-annex get foo/" - will fail if no files in the directory are checked into git, but if - at least one file is, it will ignore other files that are not. This is - all the same as the behavior of "git-ls files --error-unmatch". - - Also note that git-annex skips files that are checked into git, but are - not annexed files, this setting does not affect that. - -* `annex.largefiles` - - Used to configure which files are large enough to be added to the annex. - It is an expression that matches the large files, eg - "`include=*.mp3 or largerthan=500kb`" - See [[git-annex-matching-expression]](1) for details on the syntax. - - Overrides any annex.largefiles attributes in `.gitattributes` files. - - To configure a default annex.largefiles for all clones of the repository, - this can be set in [[git-annex-config]](1). - - This configures the behavior of both git-annex and git when adding - files to the repository. By default, `git-annex add` adds all files - to the annex (except dotfiles), and `git add` adds files to git - (unless they were added to the annex previously). - When annex.largefiles is configured, both - `git annex add` and `git add` will add matching large files to the - annex, and the other files to git. - - Other git-annex commands also honor annex.largefiles, including - `git annex import`, `git annex addurl`, `git annex importfeed`, - `git-annex assist`, and the `git-annex assistant`. - -* `annex.dotfiles` - - Normally, dotfiles are assumed to be files like .gitignore, - whose content should always be part of the git repository, so - they will not be added to the annex. Setting annex.dotfiles to true - makes dotfiles be added to the annex the same as any other file. - - To annex only some dotfiles, set this and configure annex.largefiles - to match the ones you want. For example, to match only dotfiles ending - in ".big" - - git config annex.largefiles "(include=.*.big or include=*/.*.big) or (exclude=.* and exclude=*/.*)" - git config annex.dotfiles true - - To configure a default annex.dotfiles for all clones of the repository, - this can be set in [[git-annex-config]](1). - -* `annex.gitaddtoannex` - - Setting this to false will prevent `git add` from adding - files to the annex, despite the annex.largefiles configuration. - -* `annex.addsmallfiles` - - Controls whether small files (not matching annex.largefiles) - should be checked into git by `git annex add`. Defaults to true; - set to false to instead make small files be skipped. - -* `annex.addunlocked` - - Commands like `git-annex add` default to adding files to the repository - in locked form. This can make them add the files in unlocked form, - the same as if [[git-annex-unlock]](1) were run on the files. - - This can be set to "true" to add everything unlocked, or it can be a more - complicated expression that matches files by name, size, or content. See - [[git-annex-matching-expression]](1) for details. - - To configure a default annex.addunlocked for all clones of the repository, - this can be set in [[git-annex-config]](1). - - (Using `git add` always adds files in unlocked form and it is not - affected by this setting.) - - When a repository has core.symlinks set to false, or has an adjusted - unlocked branch checked out, this setting is ignored, and files are - always added to the repository in unlocked form. - -* `annex.numcopies` - - This is a deprecated setting. You should instead use the - `git annex numcopies` command to configure how many copies of files - are kept across all repositories, or the annex.numcopies .gitattributes - setting. - - This config setting is only looked at when `git annex numcopies` has - never been configured, and when there's no annex.numcopies setting in the - .gitattributes file. - -* `annex.genmetadata` - - Set this to `true` to make git-annex automatically generate some metadata - when adding files to the repository. - - In particular, it stores year, month, and day metadata, from the file's - modification date. - - When importfeed is used, it stores additional metadata from the feed, - such as the author, title, etc. - -* `annex.used-refspec` - - This controls which refs `git-annex unused` considers to be used. - See REFSPEC FORMAT in [[git-annex-unused]](1) for details. - -* `annex.jobs` - - Configure the number of concurrent jobs to run. Default is 1. - - Only git-annex commands that support the --jobs option will - use this. - - Setting this to "cpus" will run one job per CPU core. - - When the `--batch` option is used, this configuration is ignored. - -* `annex.adjustedbranchrefresh` - - When [[git-annex-adjust]](1) is used to set up an adjusted branch - that needs to be refreshed after getting or dropping files, this config - controls how frequently the branch is refreshed. - - Refreshing the branch takes some time, so doing it after every file - can be too slow. (It also can generate a lot of dangling git objects.) - The default value is 0 (or false), which does not - refresh the branch. Setting 1 (or true) will refresh only once, - after git-annex has made other changes. Setting 2 refreshes after every - file, 3 after every other file, and so on; setting 100 refreshes after - every 99 files. - - (If git-annex gets faster in the future, refresh rates will increase - proportional to the speed improvements.) - -* `annex.queuesize` - - git-annex builds a queue of git commands, in order to combine similar - commands for speed. By default the size of the queue is limited to - 10240 commands; this can be used to change the size. If you have plenty - of memory and are working with very large numbers of files, increasing - the queue size can speed it up. - -* `annex.bloomcapacity` - - The `git annex unused` and `git annex sync --content` commands use - a bloom filter to determine what files are present in eg, the work tree. - The default bloom filter is sized to handle - up to 500000 files. If your repository is larger than that, - you should increase this value. Larger values will - make `git-annex unused` and `git annex sync --content` consume more memory; - run `git annex info` for memory usage numbers. - -* `annex.bloomaccuracy` - - Adjusts the accuracy of the bloom filter used by - `git annex unused` and `git annex sync --content`. - The default accuracy is 10000000 -- 1 unused file out of 10000000 - will be missed by `git annex unused`. Increasing the accuracy will make - `git annex unused` consume more memory; run `git annex info` - for memory usage numbers. - -* `annex.sshcaching` - - By default, git-annex caches ssh connections using ssh's - ControlMaster and ControlPersist settings - (if built using a new enough ssh). To disable this, set to `false`. - -* `annex.adviceNoSshCaching` - - When git-annex is unable to use ssh connection caching, or has been - configured not to, and concurrency is enabled, it will warn that - this might result in multiple ssh processes prompting for passwords - at the same time. To disable that warning, eg if you have configured ssh - connection caching yourself, or have ssh agent caching passwords, - set this to `false`. - -* `annex.alwayscommit` - - By default, git-annex automatically commits data to the git-annex branch - after each command is run. If you have a series - of commands that you want to make a single commit, you can - run the commands with `-c annex.alwayscommit=false`. You can later - commit the data by running `git annex merge` (or by automatic merges) - or `git annex sync`. - -* `annex.commitmessage` - - When git-annex updates the git-annex branch, it usually makes up - its own commit message (eg "update"), since users rarely look at or - care about changes to that branch. If you do care, you can - specify this setting by running commands with - `-c annex.commitmessage=whatever` - - This works well in combination with annex.alwayscommit=false, - to gather up a set of changes and commit them with a message you specify. - -* `annex.alwayscompact` - - By default, git-annex compacts data it records in the git-annex branch. - Setting this to false avoids doing that compaction in some cases, which - can speed up operations that populate the git-annex branch with a lot - of data. However, when used with operations that overwrite old values in - the git-annex branch, that may cause the git-annex branch to use more disk - space, and so slow down reading data from it. - - An example of a command that can be sped up by using - `-c annex.alwayscompact=false` is `git-annex registerurl --batch`, - when adding a large number of urls to the same key. - - This option was first supported by git-annex version 10.20220724. - It is not entirely safe to set this option in a repository that may also - be used by an older version of git-annex at the same time as a version - that supports this option. - -* `annex.allowsign` - - By default git-annex avoids gpg signing commits that it makes when - they're not the purpose of a command, but only a side effect. - That default avoids lots of gpg password prompts when - commit.gpgSign is set. A command like `git annex sync` or `git annex merge` - will gpg sign its commit, but a command like `git annex get`, - that updates the git-annex branch, will not. The assistant also avoids - signing commits. - - Setting annex.allowsign to true lets all commits be signed, as - controlled by commit.gpgSign and other git configuration. - -* `annex.merge-annex-branches` - - By default, git-annex branches that have been pulled from remotes - are automatically merged into the local git-annex branch, so that - git-annex has the most up-to-date possible knowledge. - - To avoid that merging, set this to "false". - - This can be useful particularly when you don't have write permission - to the repository. While git-annex is mostly able to work in a read-only - repository with unmerged git-annex branches, some things do not work, - and when it does work it will be slower due to needing to look at each of - the unmerged branches. - -* `annex.private` - - When this is set to true, no information about the repository will be - recorded in the git-annex branch. - - For example, to make a repository without any mention of it ever - appearing in the git-annex branch: - - git init myprivate - cd myprivaterepo - git config annex.private true - git annex init - -* `annex.hardlink` - - Set this to `true` to make file contents be hard linked between the - repository and its remotes when possible, instead of a more expensive copy. - - Use with caution -- This can invalidate numcopies counting, since - with hard links, fewer copies of a file can exist. So, it is a good - idea to mark a repository using this setting as untrusted. - - When a repository is set up using `git clone --shared`, git-annex init - will automatically set annex.hardlink and mark the repository as - untrusted. - - When `annex.thin` is also set, setting `annex.hardlink` has no effect. - -* `annex.thin` - - Set this to `true` to make unlocked files be a hard link to their content - in the annex, rather than a second copy. This can save considerable - disk space, but when a modification is made to a file, you will lose the - local (and possibly only) copy of the old version. Any other, locked - files in the repository that pointed to that content will get broken - as well (`git-annex fsck` will detect and clean up after that). - So, enable this with care. - - After setting (or unsetting) this, you should run `git annex fix` to - fix up the annexed files in the work tree to be hard links (or copies). - - Note that this has no effect when the filesystem does not support hard links. - And when multiple files in the work tree have the same content, only - one of them gets hard linked to the annex. - -* `annex.supportunlocked` - - By default git-annex supports unlocked files as well as locked files, - so this defaults to true. If set to false, git-annex will only support - locked files. That will avoid doing the work needed to support unlocked - files. - - Note that setting this to false does not prevent a repository from - having unlocked files added to it, and in that case the content of the - files will not be accessible until they are locked. - - After changing this config, you need to re-run `git-annex init` for it - to take effect. - -* `annex.resolvemerge` - - Set to false to prevent merge conflicts in the checked out branch - being automatically resolved by the `git-annex assitant`, - `git-annex assist`, `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, - this can be set in [[git-annex-config]](1). - -* `annex.synccontent` - - Set to true to make `git-annex sync` default to transferring - annexed content. - - Set to false to prevent `git-annex assist`, `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 assist`, `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). - -* `annex.viewunsetdirectory` - - This configures the name of a directory that is used in a view to contain - files that do not have metadata set. The default name for the directory - is `"_"`. See [[git-annex-view]](1) for details. - -* `annex.debug` - - Set to true to enable debug logging by default. - -* `annex.debugfilter` - - Set to configure which debug messages to display (when debug message - display has been enabled by annex.debug or --debug). The value is one - or more module names, separated by commas. - -* `annex.version` - - The current version of the git-annex repository. This is - maintained by git-annex and should never be manually changed. - -* `annex.autoupgraderepository` - - When an old git-annex repository version is no longer supported, - git-annex will normally automatically upgrade the repository to - the new version. It may also sometimes upgrade from an old repository - version that is still supported but that is not as good as a later - version. - - If this is set to false, git-annex won't automatically upgrade the - repository. If the repository version is not supported, git-annex - will instead exit with an error message. If it is still supported, - git-annex will continue to work. - - You can run `git annex upgrade` yourself when you are ready to upgrade the - repository. - -* `annex.crippledfilesystem` - - Set to true if the repository is on a crippled filesystem, such as FAT, - which does not support symbolic links, or hard links, or unix permissions. - This is automatically probed by "git annex init". - -* `annex.pidlock` - - Normally, git-annex uses fine-grained lock files to allow multiple - processes to run concurrently without getting in each others' way. - That works great, unless you are using git-annex on a filesystem that - does not support POSIX fcntl locks. This is sometimes the case when - using NFS or Lustre filesystems. - - To support such situations, you can set annex.pidlock to true, and it - will fall back to a single top-level pid file lock. - - Although, often, you'd really be better off fixing your networked - filesystem configuration to support POSIX locks.. And, some networked - filesystems are so inconsistent that one node can't reliably tell when - the other node is holding a pid lock. Caveat emptor. - -* `annex.pidlocktimeout` - - git-annex will wait up to this many seconds for the pid lock - file to go away, and will then abort if it cannot continue. Default: 300 - - When using pid lock files, it's possible for a stale lock file to get - left behind by previous run of git-annex that crashed or was interrupted. - This is mostly avoided, but can occur especially when using a network - file system. This timeout prevents git-annex waiting forever in such a - situation. - -* `annex.dbdir` - - The directory where git-annex should store its sqlite databases. - The default location is inside `.git/annex/`. - - Certian filesystems, such as cifs, may not support locking operations - that sqlite needs, and setting this to a directory on another filesystem - can work around such a problem. - - This can safely be set to the same directory in the configuration of - multiple repositories; each repository will use a subdirectory for its - sqlite database. - -* `annex.cachecreds` - - When "true" (the default), git-annex will cache credentials used to - access special remotes in files in .git/annex/creds/ - that only you can read. To disable that caching, set to "false", - and credentials will only be read from the environment, or if - they have been embedded in encrypted form in the git repository, will - be extracted and decrypted each time git-annex needs to access the - remote. - -* `annex.secure-erase-command` - - This can be set to a command that should be run whenever git-annex - removes the content of a file from the repository. - - In the command line, %file is replaced with the file that should be - erased. - - For example, to use the wipe command, set it to `wipe -f %file`. - -* `annex.freezecontent-command`, `annex.thawcontent-command` - - Usually the write permission bits are unset to protect annexed objects - from being modified or deleted. The freezecontent-command is run after - git-annex has removed (or attempted to remove) the write bit, and can - be used to prevent writing in some other way. - The thawcontent-command should undo its effect, and is run before - git-annex restores the write bit. - - In the command line, %path is replaced with the file or directory to - operate on. - - (When annex.crippledfilesystem is set, git-annex will not try to - remove/restore the write bit, but it will still run these hooks.) - -* `annex.tune.objecthash1`, `annex.tune.objecthashlower`, `annex.tune.branchhash1` - - These can be passed to `git annex init` to tune the repository. - They cannot be safely changed in a running repository and should never be - set in global git configuration. - For details, see . - -# CONFIGURATION OF REMOTES - -Remotes are configured using these settings in `.git/config`. - -* `remote..annex-cost` - - When determining which repository to - transfer annexed files from or to, ones with lower costs are preferred. - The default cost is 100 for local repositories, and 200 for remote - repositories. - -* `remote..annex-cost-command` - - If set, the command is run, and the number it outputs is used as the cost. - This allows varying the cost based on e.g., the current network. - -* `remote..annex-start-command` - - A command to run when git-annex begins to use the remote. This can - be used to, for example, mount the directory containing the remote. - - The command may be run repeatedly when multiple git-annex processes - are running concurrently. - -* `remote..annex-stop-command` - - A command to run when git-annex is done using the remote. - - The command will only be run once *all* running git-annex processes - are finished using the remote. - -* `remote..annex-shell` - - Specify an alternative git-annex-shell executable on the remote - instead of looking for "git-annex-shell" on the PATH. - - This is useful if the git-annex-shell program is outside the PATH - or has a non-standard name. - -* `remote..annex-ignore` - - If set to `true`, prevents git-annex - 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 - without git-annex-shell. (For example, if it's on GitHub). - 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`, `git-annex pull`, `git-annex push`, - `git-annex assist` or the `git-annex assistant` from operating on the - git repository. - -* `remote..annex-ignore-command` - - If set, the command is run, and if it exits nonzero, that's the same - as setting annex-ignore to true. This allows controlling behavior based - on e.g., the current network. - -* `remote..annex-sync` - - If set to `false`, prevents `git-annex sync` (and `git-annex pull`, - `git-annex push`, `git-annex assist`, and the `git-annex assistant`) - from operating on this remote by default. - -* `remote..annex-sync-command` - - If set, the command is run, and if it exits nonzero, that's the same - as setting annex-sync to false. This allows controlling behavior based - on e.g., the current network. - -* `remote..annex-pull` - - If set to `false`, prevents `git-annex pull`, `git-annex sync`, - `git-annex assist` and the `git-annex assistant` from ever pulling - (or fetching) from the remote. - -* `remote..annex-push` - - If set to `false`, prevents `git-annex push`, `git-annex sync`, - `git-annex assist` and the `git-annex assistant` from ever pushing - to the remote. - -* `remote..annex-readonly` - - If set to `true`, prevents git-annex from making changes to a remote. - This prevents `git-annex sync` and `git-annex assist` from pushing - changes to a git repository. And it prevents storing or removing - files from read-only remote. - -* `remote..annex-verify`, `annex.verify` - - By default, git-annex will verify the checksums of objects downloaded - from remotes. If you trust a remote and don't want the overhead - of these checksums, you can set this to `false`. - - Note that even when this is set to `false`, git-annex does verification - in some edge cases, where it's likely the case than an - object was downloaded incorrectly, or when needed for security. - -* `remote..annex-tracking-branch` - - This is for use with special remotes that support exports and imports. - - When set to eg, "master", this tells git-annex that you want the - special remote to track that branch. - - When set to eg, "master:subdir", the special remote tracks only - the subdirectory of that branch. - - Setting this enables some other command to work with these special - remotes: `git-annex pull` will import changes from the remote and merge them into - the annex-tracking-branch. And `git-annex push` will export changes to - the remote. Higher-level commands `git-annex sync --content` - and `git-annex assist` both import and export. - -* `remote..annex-export-tracking` - - Deprecated name for `remote..annex-tracking-branch`. Will still be used - if it's configured and `remote..annex-tracking-branch` is not. - -* `remote..annexUrl` - - Can be used to specify a different url than the regular `remote..url` - for git-annex to use when talking with the remote. Similar to the `pushUrl` - used by git-push. - -* `remote..annex-uuid` - - git-annex caches UUIDs of remote repositories here. - -* `remote..annex-config-uuid` - - Used for some special remotes, points to a different special remote - configuration to use. - -* `remote..annex-retry`, `annex.retry` - - Number of times a transfer that fails can be retried. (default 0) - -* `remote..annex-forward-retry`, `annex.forward-retry` - - If a transfer made some forward progress before failing, - this allows it to be retried even when `annex.retry` does not. - The value is the maximum number of times to do that. (default 5) - - When both `annex.retry` and this are set, the maximum number of - retries is the larger of the two. - -* `remote..annex-retry-delay`, `annex.retry-delay` - - Number of seconds to delay before the first retry of a transfer. - When making multiple retries of the same transfer, the delay - doubles after each retry. (default 1) - -* `remote..annex-bwlimit`, `annex.bwlimit` - - This can be used to limit how much bandwidth is used for a transfer - from or to a remote. - - For example, to limit transfers to 1 mebibyte per second: - `git config annex.bwlimit "1MiB"` - - This will work with many remotes, including git remotes, but not - for remotes where the transfer is run by a separate program than - git-annex. - -* `remote..annex-stalldetecton`, `annex.stalldetection` - - Configuring this lets stalled or too-slow transfers be detected, and - dealt with, so rather than getting stuck, git-annex will cancel the - stalled operation. The transfer will be considered to have failed, so - settings like annex.retry will control what it does next. - - By default, git-annex detects transfers that have probably stalled, - and suggests configuring this. If it is incorrectly detecting - stalls, setting this to "false" will avoid that. - - Set to "true" to enable automatic stall detection. If a remote does not - update its progress consistently, no automatic stall detection will be - done. And it may take a while for git-annex to decide a remote is really - stalled when using automatic stall detection, since it needs to be - conservative about what looks like a stall. - - For more fine control over what constitutes a stall, set to a value in - the form "$amount/$timeperiod" to specify how much data git-annex should - expect to see flowing, minimum, over a given period of time. - - For example, to detect outright stalls where no data has been transferred - after 30 seconds: `git config annex.stalldetection "1KB/30s"` - - Or, if you have a remote on a USB drive that is normally capable of - several megabytes per second, but has bad sectors where it gets - stuck for a long time, you could use: - `git config remote.usbdrive.annex-stalldetection "1MB/1m"` - - This is not enabled by default, because it can make git-annex use - more resources. To be able to cancel stalls, git-annex has to run - transfers in separate processes (one per concurrent job). So it - may need to open more connections to a remote than usual, or - the communication with those processes may make it a bit slower. - -* `remote..annex-checkuuid` - - This only affects remotes that have their url pointing to a directory on - the same system. git-annex normally checks the uuid of such - remotes each time it's run, which lets it transparently deal with - different drives being mounted to the location at different times. - - Setting annex-checkuuid to false will prevent it from checking the uuid - at startup (although the uuid is still verified before making any - changes to the remote repository). This may be useful to set to prevent - unnecessary spin-up or automounting of a drive. - -* `remote..annex-trustlevel` - - Configures a local trust level for the remote. This overrides the value - configured by the trust and untrust commands. The value can be any of - "trusted", "semitrusted" or "untrusted". - -* `remote..annex-availability` - - Can be used to tell git-annex whether a remote is LocallyAvailable - or GloballyAvailable. Normally, git-annex determines this automatically. - -* `remote..annex-speculate-present` - - Set to "true" to make git-annex speculate that this remote may contain the - content of any file, even though its normal location tracking does not - indicate that it does. This will cause git-annex to try to get all file - contents from the remote. Can be useful in setting up a caching remote. - -* `remote..annex-private` - - When this is set to true, no information about the remote will be - recorded in the git-annex branch. This is mostly useful for special - remotes, and is set when using [[git-annex-initremote]](1) with the - `--private` option. - -* `remote..annex-bare` - - Can be used to tell git-annex if a remote is a bare repository - or not. Normally, git-annex determines this automatically. - -* `remote..annex-ssh-options` - - Options to use when using ssh to talk to this remote. - -* `remote..annex-rsync-options` - - Options to use when using rsync - to or from this remote. For example, to force IPv6, and limit - the bandwidth to 100Kbyte/s, set it to `-6 --bwlimit 100` - - Note that git-annex-shell has a whitelist of allowed rsync options, - and others will not be be passed to the remote rsync. So using some - options may break the communication between the local and remote rsyncs. - -* `remote..annex-rsync-upload-options` - - Options to use when using rsync to upload a file to a remote. - - These options are passed after other applicable rsync options, - so can be used to override them. For example, to limit upload bandwidth - to 10Kbyte/s, set `--bwlimit 10`. - -* `remote..annex-rsync-download-options` - - Options to use when using rsync to download a file from a remote. - - These options are passed after other applicable rsync options, - so can be used to override them. - -* `remote..annex-rsync-transport` - - The remote shell to use to connect to the rsync remote. Possible - values are `ssh` (the default) and `rsh`, together with their - arguments, for instance `ssh -p 2222 -c blowfish`; Note that the - remote hostname should not appear there, see rsync(1) for details. - When the transport used is `ssh`, connections are automatically cached - unless `annex.sshcaching` is unset. - -* `remote..annex-bup-split-options` - - Options to pass to bup split when storing content in this remote. - For example, to limit the bandwidth to 100Kbyte/s, set it to `--bwlimit 100k` - (There is no corresponding option for bup join.) - -* `remote..annex-gnupg-options` - - Options to pass to GnuPG when it's encrypting data. For instance, to - use the AES cipher with a 256 bits key and disable compression, set it - to `--cipher-algo AES256 --compress-algo none`. (These options take - precedence over the default GnuPG configuration, which is otherwise - used.) - -* `remote..annex-gnupg-decrypt-options` - - Options to pass to GnuPG when it's decrypting data. (These options take - precedence over the default GnuPG configuration, which is otherwise - used.) - -* `annex.ssh-options`, `annex.rsync-options`, - `annex.rsync-upload-options`, `annex.rsync-download-options`, - `annex.bup-split-options`, `annex.gnupg-options`, - `annex.gnupg-decrypt-options` - - Default options to use if a remote does not have more specific options - as described above. - -* `remote..annex-rsyncurl` - - Used by rsync special remotes, this configures - the location of the rsync repository to use. Normally this is automatically - set up by `git annex initremote`, but you can change it if needed. - -* `remote..annex-buprepo` - - Used by bup special remotes, this configures - the location of the bup repository to use. Normally this is automatically - set up by `git annex initremote`, but you can change it if needed. - -* `remote..annex-borgrepo` - - Used by borg special remotes, this configures - the location of the borg repository to use. Normally this is automatically - set up by `git annex initremote`, but you can change it if needed. - -* `remote..annex-ddarrepo` - - Used by ddar special remotes, this configures - the location of the ddar repository to use. Normally this is automatically - set up by `git annex initremote`, but you can change it if needed. - -* `remote..annex-directory` - - Used by directory special remotes, this configures - the location of the directory where annexed files are stored for this - remote. Normally this is automatically set up by `git annex initremote`, - but you can change it if needed. - -* `remote..annex-adb` - - Used to identify remotes on Android devices accessed via adb. - Normally this is automatically set up by `git annex initremote`. - -* `remote..annex-androiddirectory` - - Used by adb special remotes, this is the directory on the Android - device where files are stored for this remote. Normally this is - automatically set up by `git annex initremote`, but you can change - it if needed. - -* `remote..annex-androidserial` - - Used by adb special remotes, this is the serial number of the Android - device used by the remote. Normally this is automatically set up by - `git annex initremote`, but you can change it if needed, eg when - upgrading to a new Android device. - -* `remote..annex-s3` - - Used to identify Amazon S3 special remotes. - Normally this is automatically set up by `git annex initremote`. - -* `remote..annex-glacier` - - Used to identify Amazon Glacier special remotes. - Normally this is automatically set up by `git annex initremote`. - -* `remote..annex-web` - - Used to identify web special remotes. - Normally this is automatically set up by `git annex initremote`. - -* `remote..annex-webdav` - - Used to identify webdav special remotes. - Normally this is automatically set up by `git annex initremote`. - -* `remote..annex-tahoe` - - Used to identify tahoe special remotes. - Points to the configuration directory for tahoe. - -* `remote..annex-gcrypt` - - Used to identify gcrypt special remotes. - Normally this is automatically set up by `git annex initremote`. - - It is set to "true" if this is a gcrypt remote. - If the gcrypt remote is accessible over ssh and has git-annex-shell - available to manage it, it's set to "shell". - -* `remote..annex-git-lfs` - - Used to identify git-lfs special remotes. - Normally this is automatically set up by `git annex initremote`. - - It is set to "true" if this is a git-lfs remote. - -* `remote..annex-httpalso` - - Used to identify httpalso special remotes. - Normally this is automatically set up by `git annex initremote`. - -* `remote..annex-externaltype` - - Used external special remotes to record the type of the remote. - - Eg, if this is set to "foo", git-annex will run a "git-annex-remote-foo" - program to communicate with the external special remote. - - If this is set to "readonly", then git-annex will not run any external - special remote program, but will try to access things stored in the - remote using http. That only works for some external special remotes, - so consult the documentation of the one you are using. - -* `remote..annex-hooktype` - - Used by hook special remotes to record the type of the remote. - -* `annex.web-options` - - Options to pass to curl when git-annex uses it to download urls - (rather than the default built-in url downloader). - - For example, to force IPv4 only, set it to "-4". - - Setting this option makes git-annex use curl, but only - when annex.security.allowed-ip-addresses is configured in a - specific way. See its documentation. - - Setting this option prevents git-annex from using git-credential - for prompting for http passwords. Instead, you can include "--netrc" - to make curl use your ~/.netrc file and record the passwords there. - -* `annex.youtube-dl-options` - - Options to pass to yt-dlp (or deprecated youtube-dl) when using it to - find the url to download for a video. - - Some options may break git-annex's integration with yt-dlp. For - example, the --output option could cause it to store files somewhere - git-annex won't find them. Avoid setting here or in the yt-dlp config - file any options that cause it to download more than one file, - or to store the file anywhere other than the current working directory. - -* `annex.youtube-dl-command` - - Default is to use "yt-dlp" or if that is not available in the PATH, - to use "youtube-dl". - -* `annex.aria-torrent-options` - - Options to pass to aria2c when using it to download a torrent. - -* `annex.http-headers` - - HTTP headers to send when downloading from the web. Multiple lines of - this option can be set, one per header. - -* `annex.http-headers-command` - - If set, the command is run and each line of its output is used as a HTTP - header. This overrides annex.http-headers. - -* `annex.security.allowed-url-schemes` - - List of URL schemes that git-annex is allowed to download content from. - The default is "http https ftp". - - Think very carefully before changing this; there are security - implications. For example, if it's changed to allow "file" URLs, then - anyone who can get a commit into your git-annex repository could - `git-annex addurl` a pointer to a private file located outside that - repository, possibly causing it to be copied into your repository - and transferred on to other remotes, exposing its content. - - Any url schemes supported by curl can be listed here, but you will - also need to configure annex.allowed-ip-addresses to allow using curl. - - Some special remotes support their own domain-specific URL - schemes; those are not affected by this configuration setting. - -* `annex.security.allowed-ip-addresses` - - By default, git-annex only makes connections to public IP addresses; - it will refuse to use HTTP and other servers on localhost or on a - private network. - - This setting can override that behavior, allowing access to particular - IP addresses that would normally be blocked. For example "127.0.0.1 ::1" - allows access to localhost (both IPV4 and IPV6). - To allow access to all IP addresses, use "all" - - Think very carefully before changing this; there are security - implications. Anyone who can get a commit into your git-annex repository - could `git annex addurl` an url on a private server, possibly - causing it to be downloaded into your repository and transferred to - other remotes, exposing its content. - - Note that, since the interfaces of curl and yt-dlp do not allow - these IP address restrictions to be enforced, curl and yt-dlp will - never be used unless annex.security.allowed-ip-addresses=all. - - To allow accessing local or private IP addresses on only specific ports, - use the syntax "[addr]:port". For example, - "[127.0.0.1]:80 [127.0.0.1]:443 [::1]:80 [::1]:443" allows - localhost on the http ports only. - -* `annex.security.allowed-http-addresses` - - Old name for annex.security.allowed-ip-addresses. - If set, this is treated the same as having - annex.security.allowed-ip-addresses set. - -* `annex.security.allow-unverified-downloads` - - For security reasons, git-annex refuses to download content from - most special remotes when it cannot check a hash to verify - that the correct content was downloaded. This particularly impacts - downloading the content of URL or WORM keys, which lack hashes. - - The best way to avoid problems due to this is to migrate files - away from such keys, before their content reaches a special remote. - See [[git-annex-migrate]](1). - - When the content is only available from a special remote, you can - use this configuration to force git-annex to download it. - But you do so at your own risk, and it's very important you read and - understand the information below first! - - Downloading unverified content from encrypted special remotes is - prevented, because the special remote could send some other encrypted - content than what you expect, causing git-annex to decrypt data that you - never checked into git-annex, and risking exposing the decrypted - data to any non-encrypted remotes you send content to. - - Downloading unverified content from (non-encrypted) - external special remotes is prevented, because they could follow - http redirects to web servers on localhost or on a private network, - or in some cases to a file:/// url. - - If you decide to bypass this security check, the best thing to do is - to only set it temporarily while running the command that gets the file. - The value to set the config to is "ACKTHPPT". - For example: - - git -c annex.security.allow-unverified-downloads=ACKTHPPT annex get myfile - - It would be a good idea to check that it downloaded the file you expected, - too. - -* `remote..annex-security-allow-unverified-downloads` - - Per-remote configuration of annex.security.allow-unverified-downloads. - -# CONFIGURATION OF ASSISTANT - -* `annex.delayadd` - - Makes the watch and assistant commands delay for the specified number of - seconds before adding a newly created file to the annex. Normally this - is not needed, because they already wait for all writers of the file - to close it. - - Note that this only delays adding files created while the daemon is - running. Changes made when it is not running will be added immediately - the next time it is started up. - -* `annex.expireunused` - - Controls what the assistant does about unused file contents - that are stored in the repository. - - The default is `false`, which causes - all old and unused file contents to be retained, unless the assistant - is able to move them to some other repository (such as a backup repository). - - Can be set to a time specification, like "7d" or "1m", and then - file contents that have been known to be unused for a week or a - month will be deleted. - -* `annex.fscknudge` - - When set to false, prevents the webapp from reminding you when using - repositories that lack consistency checks. - -* `annex.autoupgrade` - - When set to ask (the default), the webapp will check for new versions - and prompt if they should be upgraded to. When set to true, automatically - upgrades without prompting (on some supported platforms). When set to - false, disables any upgrade checking. - - Note that upgrade checking is only done when git-annex is installed - from one of the prebuilt images from its website. This does not - bypass e.g., a Linux distribution's own upgrade handling code. - - This setting also controls whether to restart the git-annex assistant - when the git-annex binary is detected to have changed. That is useful - no matter how you installed git-annex. - -* `annex.autocommit` - - Set to false to prevent the `git-annex assistant`, `git-annex assist`, - and `git-annex sync` from automatically committing changes to files in - the repository. - - To configure the behavior in all clones of the repository, - this can be set in [[git-annex-config]](1). - -* `annex.startupscan` - - Set to false to prevent the git-annex assistant from scanning the - repository for new and changed files on startup. This will prevent it - from noticing changes that were made while it was not running, but can be - a useful performance tweak for a large repository. - -* `annex.listen` - - Configures which address the webapp listens on. The default is localhost. - Can be either an IP address, or a hostname that resolves to the desired - address. - -# CONFIGURATION VIA .gitattributes - -The key-value backend used when adding a new file to the annex can be -configured on a per-file-type basis via `.gitattributes` files. In the file, -the `annex.backend` attribute can be set to the name of the backend to -use. (See [[git-annex-backends]](1) for information about -available backends.) -For example, this here's how to use the WORM backend by default, -but the SHA256E backend for ogg files: - - * annex.backend=WORM - *.ogg annex.backend=SHA256E - -There is a annex.largefiles attribute, which is used to configure which -files are large enough to be added to the annex. Since attributes cannot -contain spaces, it is difficult to use for more complex annex.largefiles -settings. Setting annex.largefiles in [[git-annex-config]](1) is an easier -way to configure it across all clones of the repository. -See [[git-annex-matching-expression]](1) for details on the syntax. - -The numcopies and mincopies settings can also be configured on a -per-file-type basis via the `annex.numcopies` and `annex.mincopies` -attributes in `.gitattributes` files. This overrides other settings. -For example, this makes two copies be needed for wav files and 3 copies -for flac files: - - *.wav annex.numcopies=2 - *.flac annex.numcopies=3 - -These settings are honored by git-annex whenever it's operating on a -matching file. However, when using --all, --unused, or --key to specify -keys to operate on, git-annex is operating on keys and not files, so will -not honor the settings from .gitattributes. For this reason, the `git annex -numcopies` and `git annex mincopies` commands are useful to configure a -global default. - -Also note that when using views, only the toplevel .gitattributes file is -preserved in the view, so other settings in other files won't have any -effect. - -# EXIT STATUS - -git-annex itself will exit 0 on success and 1 on failure, unless -the `--size-limit` or `--time-limit` option is hit, in -which case it exits 101. - -A few git-annex subcommands have other exit statuses used to indicate -specific problems, which are documented on their individual man pages. - -# ENVIRONMENT - -These environment variables are used by git-annex when set: - -* `GIT_WORK_TREE`, `GIT_DIR` - - Handled the same as they are by git, see git(1) - -* `GIT_SSH`, `GIT_SSH_COMMAND` - - Handled similarly to the same as described in git(1). - The one difference is that git-annex will sometimes pass an additional - "-n" parameter to these, as the first parameter, to prevent ssh from - reading from stdin. Since that can break existing uses of these - environment variables that don't expect the extra parameter, you will - need to set `GIT_ANNEX_USE_GIT_SSH=1` to make git-annex support - these. - - Note that setting either of these environment variables prevents - git-annex from automatically enabling ssh connection caching - (see `annex.sshcaching`), so it will slow down some operations with - remotes over ssh. It's up to you to enable ssh connection caching - if you need it; see ssh's documentation. - - Also, `annex.ssh-options` and `remote..annex-ssh-options` - won't have any effect when these envionment variables are set. - - Usually it's better to configure any desired options through your - ~/.ssh/config file, or by setting `annex.ssh-options`. - -* `GIT_ANNEX_VECTOR_CLOCK` - - Normally git-annex timestamps lines in the log files committed to the - git-annex branch. Setting this environment variable to a number - will make git-annex use that (or a larger number) - rather than the current number of seconds since the UNIX epoch. - Note that decimal seconds are supported. - - This is only provided for advanced users who either have a better way to - tell which commit is current than the local clock, or who need to avoid - embedding timestamps for policy reasons. - -* Some special remotes use additional environment variables - for authentication etc. For example, `AWS_ACCESS_KEY_ID` - and `GIT_ANNEX_P2P_AUTHTOKEN`. See special remote documentation. - -# FILES - -These files are used by git-annex: - -`.git/annex/objects/` in your git repository contains the annexed file -contents that are currently available. Annexed files in your git -repository symlink to that content. - -`.git/annex/` in your git repository contains other run-time information -used by git-annex. - -`~/.config/git-annex/autostart` is a list of git repositories -to start the git-annex assistant in. - -`.git/hooks/pre-commit-annex` in your git repository will be run whenever -a commit is made to the HEAD branch, either by git commit, git-annex -sync, or the git-annex assistant. - -`.git/hooks/post-update-annex` in your git repository will be run -whenever the git-annex branch is updated. You can make this hook run -`git update-server-info` when publishing a git-annex repository by http. - -# SEE ALSO - -More git-annex documentation is available on its web site, - - -If git-annex is installed from a package, a copy of its documentation -should be included, in, for example, `/usr/share/doc/git-annex/`. - -# AUTHOR - -Joey Hess - - - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-remote-tor-annex.mdwn b/doc/git-remote-tor-annex.mdwn deleted file mode 100644 --- a/doc/git-remote-tor-annex.mdwn +++ /dev/null @@ -1,36 +0,0 @@ -# NAME - -git-remote-tor-annex - remote helper program to talk to git-annex over tor - -# SYNOPSIS - -git fetch tor-annex::address.onion:port - -git remote add tor tor-annex::address.onion:port - -# DESCRIPTION - -This is a git remote helper program that allows git to pull and push -over tor(1), communicating with a tor hidden service. - -The tor hidden service probably requires an authtoken to use it. -The authtoken can be provided in the environment variable -`GIT_ANNEX_P2P_AUTHTOKEN`. Or, if there is a file in -`.git/annex/creds/` matching the onion address of the hidden -service, its first line is used as the authtoken. - -# SEE ALSO - -git-remote-helpers(1) - -[[git-annex]](1) - -[[git-annex-enable-tor]](1) - -[[git-annex-remotedaemon]](1) - -# AUTHOR - -Joey Hess - -Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/git-annex.cabal b/git-annex.cabal --- a/git-annex.cabal +++ b/git-annex.cabal @@ -1,5 +1,5 @@ Name: git-annex -Version: 10.20230802 +Version: 10.20230828 Cabal-Version: 1.12 License: AGPL-3 Maintainer: Joey Hess @@ -19,7 +19,7 @@ . It can store large files in many places, from local hard drives, to a large number of cloud storage services, including S3, WebDAV, - and rsync, with a dozen cloud storage providers usable via plugins. + and rsync, and many other usable via plugins. Files can be stored encrypted with gpg, so that the cloud storage provider cannot see your data. git-annex keeps track of where each file is stored, so it knows how many copies are available, and has many @@ -30,9 +30,9 @@ to git and transferring them to other computers. The git-annex webapp makes it easy to set up and use git-annex this way. -- The tarball uploaded to hackage does not include every non-haskell --- file in the git repo. The website is left out, so is build machinery for --- standalone apps, and packages. Include only files that are needed --- make cabal install git-annex work. +-- file in the git repo. The website is left out, as are man pages, +-- so is build machinery for standalone apps, and packages. +-- Include only files that are needed make cabal install git-annex work. Extra-Source-Files: stack.yaml stack-lts-18.13.yaml @@ -41,123 +41,8 @@ NEWS doc/license/GPL doc/license/AGPL - doc/git-annex.mdwn - doc/git-annex-add.mdwn - doc/git-annex-addunused.mdwn - doc/git-annex-addurl.mdwn - doc/git-annex-adjust.mdwn - doc/git-annex-assist.mdwn - doc/git-annex-assistant.mdwn - doc/git-annex-backends.mdwn - doc/git-annex-calckey.mdwn - doc/git-annex-checkpresentkey.mdwn - doc/git-annex-config.mdwn - doc/git-annex-configremote.mdwn - doc/git-annex-contentlocation.mdwn - doc/git-annex-copy.mdwn - doc/git-annex-dead.mdwn - doc/git-annex-describe.mdwn - doc/git-annex-diffdriver.mdwn - doc/git-annex-direct.mdwn - doc/git-annex-drop.mdwn - doc/git-annex-dropkey.mdwn - doc/git-annex-dropunused.mdwn - doc/git-annex-edit.mdwn - doc/git-annex-enableremote.mdwn - doc/git-annex-enable-tor.mdwn - doc/git-annex-examinekey.mdwn - doc/git-annex-expire.mdwn - doc/git-annex-export.mdwn - doc/git-annex-filter-branch.mdwn - doc/git-annex-find.mdwn - doc/git-annex-findkeys.mdwn - doc/git-annex-findref.mdwn - doc/git-annex-fix.mdwn - doc/git-annex-forget.mdwn - doc/git-annex-fromkey.mdwn - doc/git-annex-fsck.mdwn - doc/git-annex-fuzztest.mdwn - doc/git-annex-get.mdwn - doc/git-annex-group.mdwn - doc/git-annex-groupwanted.mdwn - doc/git-annex-import.mdwn - doc/git-annex-importfeed.mdwn - doc/git-annex-indirect.mdwn - doc/git-annex-info.mdwn - doc/git-annex-init.mdwn - doc/git-annex-initremote.mdwn - doc/git-annex-inprogress.mdwn - doc/git-annex-list.mdwn - doc/git-annex-lock.mdwn - doc/git-annex-log.mdwn - doc/git-annex-lookupkey.mdwn - doc/git-annex-map.mdwn - doc/git-annex-matchexpression.mdwn - doc/git-annex-matching-options.mdwn - doc/git-annex-merge.mdwn - doc/git-annex-metadata.mdwn - doc/git-annex-migrate.mdwn - doc/git-annex-mirror.mdwn - doc/git-annex-move.mdwn - doc/git-annex-multicast.mdwn - doc/git-annex-numcopies.mdwn - doc/git-annex-p2p.mdwn - doc/git-annex-pre-commit.mdwn - doc/git-annex-preferred-content.mdwn - doc/git-annex-proxy.mdwn - doc/git-annex-pull.mdwn - doc/git-annex-push.mdwn - doc/git-annex-readpresentkey.mdwn - doc/git-annex-registerurl.mdwn - doc/git-annex-reinit.mdwn - doc/git-annex-reinject.mdwn - doc/git-annex-rekey.mdwn - doc/git-annex-remotedaemon.mdwn - doc/git-annex-renameremote.mdwn - doc/git-annex-repair.mdwn - doc/git-annex-required.mdwn - doc/git-annex-restage.mdwn - doc/git-annex-resolvemerge.mdwn - doc/git-annex-rmurl.mdwn - doc/git-annex-satisfy.mdwn - doc/git-annex-schedule.mdwn - doc/git-annex-semitrust.mdwn - doc/git-annex-setkey.mdwn - doc/git-annex-setpresentkey.mdwn - doc/git-annex-shell.mdwn - doc/git-annex-smudge.mdwn - doc/git-annex-status.mdwn - doc/git-annex-sync.mdwn - doc/git-annex-test.mdwn - doc/git-annex-testremote.mdwn - doc/git-annex-transferkey.mdwn - doc/git-annex-transferkeys.mdwn - doc/git-annex-trust.mdwn - doc/git-annex-unannex.mdwn - doc/git-annex-undo.mdwn - doc/git-annex-ungroup.mdwn - doc/git-annex-uninit.mdwn - doc/git-annex-unlock.mdwn - doc/git-annex-untrust.mdwn - doc/git-annex-unregisterurl.mdwn - doc/git-annex-unused.mdwn - doc/git-annex-upgrade.mdwn - doc/git-annex-vadd.mdwn - doc/git-annex-vcycle.mdwn - doc/git-annex-version.mdwn - doc/git-annex-vfilter.mdwn - doc/git-annex-vicfg.mdwn - doc/git-annex-view.mdwn - doc/git-annex-vpop.mdwn - doc/git-annex-wanted.mdwn - doc/git-annex-watch.mdwn - doc/git-annex-webapp.mdwn - doc/git-annex-whereis.mdwn - doc/git-annex-whereused.mdwn - doc/git-remote-tor-annex.mdwn doc/logo.svg doc/logo_16x16.png - Build/mdwn2man Assistant/WebApp/routes static/activityicon.gif static/css/bootstrap.css @@ -776,6 +661,7 @@ Command.NotifyChanges Command.NumCopies Command.MinCopies + Command.OldKeys Command.P2P Command.P2PStdIO Command.PostReceive @@ -986,6 +872,7 @@ Remote.Helper.Http Remote.Helper.Messages Remote.Helper.P2P + Remote.Helper.Path Remote.Helper.ReadOnly Remote.Helper.ThirdPartyPopulated Remote.Helper.Special @@ -1175,6 +1062,7 @@ Utility.Touch Utility.Tuple Utility.Url + Utility.Url.Parse Utility.UserInfo Utility.Verifiable diff --git a/stack.yaml b/stack.yaml --- a/stack.yaml +++ b/stack.yaml @@ -18,6 +18,5 @@ - torrent-10000.1.1 - bencode-0.6.1.1 - feed-1.3.2.1 -- git: https://github.com/sjakobi/bloomfilter.git - commit: fb79b39c44404fd791a3bed973e9d844fb084f1e +- bloomfilter-2.0.1.2 allow-newer: true