rename describe to init and show usage

Commands.hs

@@ -23,22 +23,28 @@ import Core
 import qualified Remotes
 import qualified BackendTypes
 
-data CmdWants = FilesInGit | FilesNotInGit | FilesInOrNotInGit |
+data CmdWants = FilesInGit | FilesNotInGit | RepoName | SingleString
-		RepoName | SingleString
 data Command = Command {
 	cmdname :: String,
 	cmdaction :: (String -> Annex ()),
-	cmdwants :: CmdWants
+	cmdwants :: CmdWants,
+	cmddesc :: String
 }
 
 cmds :: [Command]
 cmds =  [
-	  (Command "add"	addCmd		FilesNotInGit)
+	  (Command "add"	addCmd		FilesNotInGit
-	, (Command "get"	getCmd		FilesInGit)
+		"add files to annex")
-	, (Command "drop"	dropCmd		FilesInGit)
+	, (Command "get"	getCmd		FilesInGit
-	, (Command "unannex"	unannexCmd	FilesInGit)
+		"make content of annexed files available")
-	, (Command "describe"	describeCmd	SingleString)
+	, (Command "drop"	dropCmd		FilesInGit
-	, (Command "fix"	fixCmd		FilesInOrNotInGit)
+		"indicate content of files not currently wanted")
+	, (Command "unannex"	unannexCmd	FilesInGit
+		"undo accidential add command")
+	, (Command "init"	initCmd		SingleString
+		"initialize git-annex with repository description")
+	, (Command "fix"	fixCmd		FilesInGit
+		"fix up files' symlinks to point to annexed content")
 	]
 
 options = [
@@ -46,6 +52,17 @@ options = [
 	  , Option ['N'] ["no-commit"] (NoArg NoCommit) "do not stage or commit changes"
 	  ]
 
+header = "Usage: git-annex [" ++ (join "|" $ map cmdname cmds) ++ "] ..."
+
+usage = usageInfo header options ++ "\nSubcommands:\n" ++ cmddescs
+	where
+		cmddescs = unlines $ map (\c -> indent $ showcmd c) cmds
+		showcmd c =
+			(cmdname c) ++
+			(take (10 - (length (cmdname c))) $ repeat ' ') ++ 
+			(cmddesc c)
+		indent l = "  " ++ l
+
 {- Finds the type of parameters a command wants, from among the passed
  - parameter list. -}
 findWanted :: CmdWants -> [String] -> Git.Repo -> IO [String]
@@ -55,10 +72,6 @@ findWanted FilesNotInGit params repo = do
 findWanted FilesInGit params repo = do
 	files <- mapM (Git.inRepo repo) params
 	return $ foldl (++) [] files
-findWanted FilesInOrNotInGit params repo = do
-	a <- findWanted FilesInGit params repo
-	b <- findWanted FilesNotInGit params repo
-	return $ union a b
 findWanted SingleString params _ = do
 	return $ [unwords params]
 findWanted RepoName params _ = do
@@ -73,7 +86,7 @@ parseCmd argv state = do
 		0 -> error usage
 		_ -> case (lookupCmd (params !! 0)) of
 			[] -> error usage
-			[Command _ action want] -> do
+			[Command _ action want _] -> do
 				f <- findWanted want (drop 1 params)
 					(BackendTypes.repo state)
 				return (flags, map action $ filter notstate f)
@@ -84,9 +97,6 @@ parseCmd argv state = do
 			(flags, params, []) -> return (flags, params)
 			(_, _, errs) -> ioError (userError (concat errs ++ usage))
 		lookupCmd cmd = filter (\c -> cmd  == cmdname c) cmds
-		header = "Usage: git-annex [" ++ 
-			(join "|" $ map cmdname cmds) ++ "] ..."
-		usage = usageInfo header options
 
 {- Annexes a file, storing it in a backend, and then moving it into
  - the annex directory and setting up the symlink pointing to its content. -}
@@ -197,32 +207,37 @@ dropCmd file = notinBackend file err $ \(key, backend) -> do
 
 {- Fixes the symlink to an annexed file. -}
 fixCmd :: String -> Annex ()
-fixCmd file = notinBackend file err $ \(key, backend) -> do
+fixCmd file = notinBackend file skip $ \(key, backend) -> do
 	link <- calcGitLink file key
-	checkLegal file link
+	l <- liftIO $ readSymbolicLink file
-	showStart "fix" file
+	if (link == l)
-	liftIO $ createDirectoryIfMissing True (parentDir file)
+		then skip
-	liftIO $ removeFile file
+		else do
-	liftIO $ createSymbolicLink link file
+			showStart "fix" file
-	gitAdd file $ Just $ "git-annex fix " ++ file
+			liftIO $ createDirectoryIfMissing True (parentDir file)
-	showEndOk
+			liftIO $ removeFile file
+			liftIO $ createSymbolicLink link file
+			gitAdd file $ Just $ "git-annex fix " ++ file
+			showEndOk
 	where
-		checkLegal file link = do
+		-- quietly skip non-annexed files, so this can be used
-			l <- liftIO $ readSymbolicLink file
+		-- as a commit hook
-			if (link == l)
+		skip = return ()
-				then error $ "symbolic link already ok for: " ++ file
-				else return ()
-		err = error $ "not annexed " ++ file
 
 {- Stores description for the repository. -}
-describeCmd :: String -> Annex ()
+initCmd :: String -> Annex ()
-describeCmd description = do
+initCmd description = do
-	g <- Annex.gitRepo
+	if (0 == length description)
-	u <- getUUID g
+		then error $ 
-	describeUUID u description
+			"please specify a description of this repository\n" ++
-	log <- uuidLog
+			usage
-	gitAdd log $ Just $ "description for UUID " ++ (show u)
+		else do
-	liftIO $ putStrLn "description set"
+			g <- Annex.gitRepo
+			u <- getUUID g
+			describeUUID u description
+			log <- uuidLog
+			gitAdd log $ Just $ "description for UUID " ++ (show u)
+			liftIO $ putStrLn "description set"
 
 -- helpers
 inBackend file yes no = do

doc/git-annex.mdwn

@@ -49,7 +49,7 @@ Enough broad picture, here's how it actually looks:
   if you're just done with a file; only use `unannex` if you
   accidentially added a file. (You can also run this on all your annexed
   files come the Singularity. ;-)
-* `git annex describe "some description"` allows associating some description
+* `git annex init "some description"` allows associating some description
   (such as "USB archive drive 1") with a repository. This can help with
   finding it later, see "Location Tracking" below.
 
@@ -128,21 +128,23 @@ is on a home file server, and you are away from home. Then git-annex can
 tell you what git remote it needs access to in order to get a file:
 
 	# git annex get myfile
-	git-annex: unable to get file with key: WORM:8b01f6d371178722367393eb26043482e1820306:myfile
+	get myfile (need access to one of these remotes: home)
-	To get that file, need access to one of these remotes: home
+	git-annex: get myfile failed
 
 Another way the location tracking comes in handy is if you put repositories
 on removable USB drives, that might be archived away offline in a safe
 place. In this sort of case, you probably don't have a git remotes
 configured for every USB drive. So git-annex may have to resort to talking
-about repository UUIDs. If you have previously used "git annex describe"
+about repository UUIDs. If you have previously used "git annex init"
-in those repositories, it will include their description to help you with
+to attach descriptions to those repositories, it will include their
-finding them:
+descriptions to help you with finding them:
 
-	git-annex: no available git remotes have file with key: WORM:8b01f6d371178722367393eb26043482e1820306:myfile
+	# git annex get myfile
-	It has been seen before in these repositories:
+	get myfile (No available git remotes have the file.)
-	  c0a28e06-d7ef-11df-885c-775af44f8882  -- USB archive drive 1
+	  It has been seen before in these repositories:
-	  e1938fee-d95b-11df-96cc-002170d25c55
+	  	c0a28e06-d7ef-11df-885c-775af44f8882  -- USB archive drive 1
+	  	e1938fee-d95b-11df-96cc-002170d25c55
+	git-annex: get myfile failed
 
 ## configuration