Update integrated help.

cmd/cmd.go

@@ -45,7 +45,14 @@ func RootCommand() *commander.Command {
 aptly is a tool to create partial and full mirrors of remote
 repositories, manage local repositories, filter them, merge,
 upgrade individual packages, take snapshots and publish them
-back as Debian repositories.`,
+back as Debian repositories.
+
+aptly goal is to establish repeatiblity and controlled changes
+in package environment. aptly allows to fix set of packages in
+repository, so that package installation and upgrade becomes
+deterministic. At the same time aptly allows to perform controlled,
+fine-grained changes in repository contents to transition your
+package environment to new version.`,
 		Flag: *flag.NewFlagSet("aptly", flag.ExitOnError),
 		Subcommands: []*commander.Command{
 			makeCmdDb(),

cmd/db.go

@@ -5,24 +5,6 @@ import (
 	"github.com/gonuts/flag"
 )
 
-func makeCmdDbCleanup() *commander.Command {
-	cmd := &commander.Command{
-		Run:       aptlyDbCleanup,
-		UsageLine: "cleanup",
-		Short:     "remove unused entries in DB and unreferenced files in the pool",
-		Long: `
-Database cleanup removes information about unreferenced packages and removes
-files in the package pool that aren't used by packages anymore
-
-ex:
-  $ aptly db cleanup
-`,
-		Flag: *flag.NewFlagSet("aptly-db-cleanup", flag.ExitOnError),
-	}
-
-	return cmd
-}
-
 func makeCmdDb() *commander.Command {
 	return &commander.Command{
 		UsageLine: "db",

cmd/db_cleanup.go

@@ -3,6 +3,7 @@ package cmd
 import (
 	"fmt"
 	"github.com/gonuts/commander"
+	"github.com/gonuts/flag"
 	"github.com/smira/aptly/debian"
 	"github.com/smira/aptly/utils"
 	"sort"
@@ -144,3 +145,22 @@ func aptlyDbCleanup(cmd *commander.Command, args []string) error {
 	}
 	return err
 }
+
+func makeCmdDbCleanup() *commander.Command {
+	cmd := &commander.Command{
+		Run:       aptlyDbCleanup,
+		UsageLine: "cleanup",
+		Short:     "cleanup DB and package pool",
+		Long: `
+Database cleanup removes information about unreferenced packages and removes
+files in the package pool that aren't used by packages anymore
+
+Example:
+
+  $ aptly db cleanup
+`,
+		Flag: *flag.NewFlagSet("aptly-db-cleanup", flag.ExitOnError),
+	}
+
+	return cmd
+}

cmd/graph.go

@@ -194,12 +194,14 @@ func makeCmdGraph() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyGraph,
 		UsageLine: "graph",
-		Short:     "display graph of dependencies between aptly objects (requires graphviz)",
+		Short:     "render graph of relationships",
 		Long: `
-Command graph displays relationship between mirrors, snapshots and published repositories using
-graphviz package to render graph as image.
+Command graph displays relationship between mirrors, local repositories,
+snapshots and published repositories using graphviz package to render
+graph as image.
+
+Example:
 
-ex:
   $ aptly graph
 `,
 		Flag: *flag.NewFlagSet("aptly-graph", flag.ExitOnError),

cmd/mirror_create.go

@@ -63,21 +63,24 @@ func makeCmdMirrorCreate() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyMirrorCreate,
 		UsageLine: "create <name> <archive url> <distribution> [<component1> ...]",
-		Short:     "create new mirror of Debian repository",
+		Short:     "create new mirror",
 		Long: `
-Create records information about new mirror and fetches Release file (it doesn't download packages).
+Creates mirror <name> of remote repository, aptly supports both regular and flat Debian repositories exported
+via HTTP. aptly would try download Release file from remote repository and verify its signature.
 
-PPA url could specified in short format when running on Debian/Ubuntu:
-  $ aptly mirror create some_ppa ppa:user/project
+PPA urls could specified in short format:
+
+  $ aptly mirror create <name> ppa:<user>/<project>
+
+Example:
 
-ex:
   $ aptly mirror create wheezy-main http://mirror.yandex.ru/debian/ wheezy main
 `,
 		Flag: *flag.NewFlagSet("aptly-mirror-create", flag.ExitOnError),
 	}
 
 	cmd.Flag.Bool("ignore-signatures", false, "disable verification of Release file signatures")
-	cmd.Flag.Bool("with-sources", false, "download source packages")
+	cmd.Flag.Bool("with-sources", false, "download source packages in addition to binary packages")
 	cmd.Flag.Var(&keyRings, "keyring", "gpg keyring to use when verifying Release file (could be specified multiple times)")
 
 	return cmd

cmd/mirror_drop.go

@@ -51,12 +51,14 @@ func makeCmdMirrorDrop() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyMirrorDrop,
 		UsageLine: "drop <name>",
-		Short:     "delete remote repository mirror",
+		Short:     "delete mirror",
 		Long: `
-Drop deletes information about remote repository mirror. Package data is not deleted
-(it could be still used by other mirrors or snapshots).
+Drop deletes information about remote repository mirror <name>. Package data is not deleted
+(it could be still used by other mirrors or snapshots).  If mirror is used as source
+to create a snapshot, aptly would refuse to delete such mirror, use flag -force to override.
+
+Example:
 
-ex:
   $ aptly mirror drop wheezy-main
 `,
 		Flag: *flag.NewFlagSet("aptly-mirror-drop", flag.ExitOnError),

cmd/mirror_list.go

@@ -43,16 +43,16 @@ func makeCmdMirrorList() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyMirrorList,
 		UsageLine: "list",
-		Short:     "list mirrors of remote repositories",
+		Short:     "list mirrors",
 		Long: `
-List shows full list of remote repositories.
+List shows full list of remote repository mirrors.
+
+Example:
 
-ex:
   $ aptly mirror list
 `,
 		Flag: *flag.NewFlagSet("aptly-mirror-list", flag.ExitOnError),
 	}
-	cmd.Flag.Bool("v", false, "enable verbose output")
 
 	return cmd
 }

cmd/mirror_show.go

@@ -67,17 +67,18 @@ func makeCmdMirrorShow() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyMirrorShow,
 		UsageLine: "show <name>",
-		Short:     "show details about remote repository mirror",
+		Short:     "show details about mirror",
 		Long: `
-Show shows full information about mirror.
+Shows detailed information about mirror.
+
+Example:
 
-ex:
   $ aptly mirror show wheezy-main
 `,
 		Flag: *flag.NewFlagSet("aptly-mirror-show", flag.ExitOnError),
 	}
 
-	cmd.Flag.Bool("with-packages", false, "show list of packages")
+	cmd.Flag.Bool("with-packages", false, "show detailed list of packages and versions stored in the mirror")
 
 	return cmd
 }

cmd/mirror_update.go

@@ -59,11 +59,14 @@ func makeCmdMirrorUpdate() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyMirrorUpdate,
 		UsageLine: "update <name>",
-		Short:     "update packages from remote mirror",
+		Short:     "update mirror",
 		Long: `
-Update downloads list of packages and package files.
+Updates remote mirror (downloads package files and meta information). When mirror is created,
+this command should be run for the first time to fetch mirror contents. This command could be
+run many times to get updated repository contents. If interrupted, command could be restarted safely.
+
+Example:
 
-ex:
   $ aptly mirror update wheezy-main
 `,
 		Flag: *flag.NewFlagSet("aptly-mirror-update", flag.ExitOnError),

cmd/publish_drop.go

@@ -37,11 +37,13 @@ func makeCmdPublishDrop() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyPublishDrop,
 		UsageLine: "drop <distribution> [<prefix>]",
-		Short:     "removes files of published repository",
+		Short:     "remove published repository",
 		Long: `
-Command removes whatever has been published under specified prefix and distribution name.
+Command removes whatever has been published under specified <prefix> and
+<distribution> name.
+
+Example:
 
-ex.
     $ aptly publish drop wheezy
 `,
 		Flag: *flag.NewFlagSet("aptly-publish-drop", flag.ExitOnError),

cmd/publish_list.go

@@ -54,11 +54,12 @@ func makeCmdPublishList() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyPublishList,
 		UsageLine: "list",
-		Short:     "displays list of published repositories",
+		Short:     "list of published repositories",
 		Long: `
-Display command displays list of currently published snapshots with information about published root.
+Display list of currently published snapshots.
+
+Example:
 
-ex.
     $ aptly publish list
 `,
 		Flag: *flag.NewFlagSet("aptly-publish-list", flag.ExitOnError),

cmd/publish_snapshot.go

@@ -114,11 +114,14 @@ func makeCmdPublishSnapshot() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyPublishSnapshot,
 		UsageLine: "snapshot <name> [<prefix>]",
-		Short:     "makes Debian repository out of snapshot",
+		Short:     "publish snapshot",
 		Long: `
-Command publish oublishes snapshot as Debian repository ready to be used by apt tools.
+Command publish publishes snapshot as Debian repository ready to be consumed
+by apt tools. Published repostiories appear under rootDir/public directory.
+Valid GPG key is required for publishing.
+
+Example:
 
-ex.
     $ aptly publish snapshot wheezy-main
 `,
 		Flag: *flag.NewFlagSet("aptly-publish-snapshot", flag.ExitOnError),

cmd/repo_add.go

@@ -187,12 +187,14 @@ func makeCmdRepoAdd() *commander.Command {
 		UsageLine: "add <name> <package file.deb>|<directory> ...",
 		Short:     "add packages to local repository",
 		Long: `
-Command adds packages to local repository. List of files or directories to be
-scanned could be specified. If importing from directory, all files matching *.deb or *.dsc
-patterns would be scanned and added to the repository. For source packages, all required
-files are added as well automatically.
+Command adds packages to local repository from .deb (binary packages) and .dsc (source packages) files.
+When importing from directory aptly would do recursive scan looking for all files matching *.deb or *.dsc
+patterns. Every file discovered would be analyzed to extract metadata, package would be created and added
+to database. Files would be imported to internal package pool. For source packages, all required files are
+added as well automatically. Extra files for source package should be in the same directory as *.dsc file.
+
+Example:
 
-ex:
   $ aptly repo add testing myapp-0.1.2.deb incoming/
 `,
 		Flag: *flag.NewFlagSet("aptly-repo-add", flag.ExitOnError),

cmd/repo_copy.go

@@ -9,12 +9,13 @@ func makeCmdRepoCopy() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyRepoMoveCopyImport,
 		UsageLine: "copy <src-name> <dst-name> <package-spec> ...",
-		Short:     "copy packages between source repos",
+		Short:     "copy packages between local repositories",
 		Long: `
 Command copy copies packages matching <package-spec> from local repo
 <src-name> to local repo <dst-name>.
 
-ex:
+Example:
+
   $ aptly repo copy testing stable 'myapp (=0.1.12)'
 `,
 		Flag: *flag.NewFlagSet("aptly-repo-copy", flag.ExitOnError),

cmd/repo_create.go

@@ -31,17 +31,20 @@ func makeCmdRepoCreate() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyRepoCreate,
 		UsageLine: "create <name>",
-		Short:     "create new local package repository",
+		Short:     "create local repository",
 		Long: `
-Creates new empty local package repository.
+Create local package repository. Repository would be empty when
+created, packages could be added from files, copied or moved from
+another local repository or imported from the mirror.
+
+Example:
 
-ex:
   $ aptly repo create testing
 `,
 		Flag: *flag.NewFlagSet("aptly-repo-create", flag.ExitOnError),
 	}
 
-	cmd.Flag.String("comment", "", "comment for the repository")
+	cmd.Flag.String("comment", "", "any text that would be used to described local repository")
 
 	return cmd
 }

cmd/repo_drop.go

@@ -51,12 +51,13 @@ func makeCmdRepoDrop() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyRepoDrop,
 		UsageLine: "drop <name>",
-		Short:     "delete local repo",
+		Short:     "delete local repository",
 		Long: `
 Drop deletes information about local repo. Package data is not deleted
 (it could be still used by other mirrors or snapshots).
 
-ex:
+Example:
+
   $ aptly repo drop local-repo
 `,
 		Flag: *flag.NewFlagSet("aptly-repo-drop", flag.ExitOnError),

cmd/repo_import.go

@@ -9,12 +9,13 @@ func makeCmdRepoImport() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyRepoMoveCopyImport,
 		UsageLine: "import <src-mirror> <dst-repo> <package-spec> ...",
-		Short:     "import package from mirror and put it into local repo",
+		Short:     "import packages from mirror to local repository",
 		Long: `
 Command import looks up packages matching <package-spec> in mirror <src-mirror>
 and copies them to local repo <dst-repo>.
 
-ex:
+Example:
+
   $ aptly repo import wheezy-main testing nginx
 `,
 		Flag: *flag.NewFlagSet("aptly-repo-import", flag.ExitOnError),

cmd/repo_list.go

@@ -48,11 +48,12 @@ func makeCmdRepoList() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyRepoList,
 		UsageLine: "list",
-		Short:     "list local package repositories",
+		Short:     "list local repositories",
 		Long: `
 List shows full list of local package repositories.
 
-ex:
+Example:
+
   $ aptly repo list
 `,
 		Flag: *flag.NewFlagSet("aptly-repo-list", flag.ExitOnError),

cmd/repo_move.go

@@ -166,12 +166,13 @@ func makeCmdRepoMove() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyRepoMoveCopyImport,
 		UsageLine: "move <src-name> <dst-name> <package-spec> ...",
-		Short:     "move packages between source repos",
+		Short:     "move packages between local repositories",
 		Long: `
 Command move moves packages matching <package-spec> from local repo
 <src-name> to local repo <dst-name>.
 
-ex:
+Example:
+
   $ aptly repo move testing stable 'myapp (=0.1.12)'
 `,
 		Flag: *flag.NewFlagSet("aptly-repo-move", flag.ExitOnError),

cmd/repo_remove.go

@@ -67,11 +67,13 @@ func makeCmdRepoRemove() *commander.Command {
 		UsageLine: "remove <name> <package-spec> ...",
 		Short:     "remove packages from local repository",
 		Long: `
-Commands removes packages matching specs from local repository. If removed
-packages are not referenced by other repos or snapshots, they can be removed
-completely (including files) by running 'aptly db cleanup'.
+Commands removes packages matching <package-spec> from local repository
+<name>. If removed packages are not referenced by other repos or
+snapshots, they can be removed completely (including files) by running
+'aptly db cleanup'.
+
+Example:
 
-ex:
   $ aptly repo remove testing 'myapp (=0.1.12)'
 `,
 		Flag: *flag.NewFlagSet("aptly-repo-add", flag.ExitOnError),

cmd/serve.go

@@ -95,12 +95,13 @@ func makeCmdServe() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlyServe,
 		UsageLine: "serve",
-		Short:     "start embedded HTTP server to serve published repositories",
+		Short:     "HTTP serve published repositories",
 		Long: `
 Command serve starts embedded HTTP server (not suitable for real production usage) to serve
 contents of public/ subdirectory of aptly's root that contains published repositories.
 
-ex:
+Example:
+
   $ aptly serve -listen=:8080
 `,
 		Flag: *flag.NewFlagSet("aptly-serve", flag.ExitOnError),

cmd/snapshot_create.go

@@ -78,19 +78,23 @@ func aptlySnapshotCreate(cmd *commander.Command, args []string) error {
 func makeCmdSnapshotCreate() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlySnapshotCreate,
-		UsageLine: "create <name> from mirror <mirror-name> | from repo <repo-name> | create <name> empty",
-		Short:     "creates immutable snapshot of mirror (local repo) contents",
+		UsageLine: "create <name> from mirror <mirror-name> | from repo <repo-name> | empty",
+		Short:     "creates snapshot of mirror (local repository) contents",
 		Long: `
-Command create .. from mirror makes persistent immutable snapshot of remote repository mirror. Snapshot could be
-published or further modified using merge, pull and other aptly features.
+Command create <name> from mirror makes persistent immutable snapshot of remote
+repository mirror. Snapshot could be published or further modified using
+merge, pull and other aptly features.
 
-Command create .. from repo makes persistent immutable snapshot of local repository. Snapshot could be processed
-as mirror snapshots, and mixed with snapshots of remote mirrors.
+Command create <name> from repo makes persistent immutable snapshot of local
+repository. Snapshot could be processed as mirror snapshots, and mixed with
+snapshots of remote mirrors.
 
-Command create .. empty creates empty snapshot that could be used as a basis for snapshot pull operations, for example.
-As snapshots are immutable, creating one empty snapshot should be enough.
+Command create <name> empty creates empty snapshot that could be used as a
+basis for snapshot pull operations, for example. As snapshots are immutable,
+creating one empty snapshot should be enough.
+
+Example:
 
-ex.
   $ aptly snapshot create wheezy-main-today from mirror wheezy-main
 `,
 		Flag: *flag.NewFlagSet("aptly-snapshot-create", flag.ExitOnError),

cmd/snapshot_diff.go

@@ -95,11 +95,15 @@ func makeCmdSnapshotDiff() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlySnapshotDiff,
 		UsageLine: "diff <name-a> <name-b>",
-		Short:     "calculates difference in packages between two snapshots",
+		Short:     "difference between two snapshots",
 		Long: `
-Command diff shows list of missing and new packages, difference in package versions between two snapshots.
+Displays difference in packages between two snapshots. Snapshot is a list
+of packages, so difference between snapshots is a difference between package
+lists. Package could be either completely missing in one snapshot, or package
+is present in both snapshots with different versions.
+
+Example:
 
-ex.
     $ aptly snapshot diff -only-matching wheezy-main wheezy-backports
 `,
 		Flag: *flag.NewFlagSet("aptly-snapshot-diff", flag.ExitOnError),

cmd/snapshot_drop.go

@@ -70,7 +70,8 @@ func makeCmdSnapshotDrop() *commander.Command {
 Drop removes information about snapshot. If snapshot is published,
 it can't be dropped.
 
-ex.
+Example:
+
     $ aptly snapshot drop wheezy-main
 `,
 		Flag: *flag.NewFlagSet("aptly-snapshot-drop", flag.ExitOnError),

cmd/snapshot_list.go

@@ -46,11 +46,12 @@ func makeCmdSnapshotList() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlySnapshotList,
 		UsageLine: "list",
-		Short:     "lists snapshots",
+		Short:     "list snapshots",
 		Long: `
 Command list shows full list of snapshots created.
 
-ex:
+Example:
+
   $ aptly snapshot list
 `,
 		Flag: *flag.NewFlagSet("aptly-snapshot-list", flag.ExitOnError),

cmd/snapshot_merge.go

@@ -60,13 +60,16 @@ func makeCmdSnapshotMerge() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlySnapshotMerge,
 		UsageLine: "merge <destination> <source> [<source>...]",
-		Short:     "merges snapshots into one, replacing matching packages",
+		Short:     "merges snapshots",
 		Long: `
-Merge merges several snapshots into one. Merge happens from left to right. Packages with the same
-name-architecture pair are replaced during merge (package from latest snapshot on the list wins).
-If run with only one source snapshot, merge copies source into destination.
+Merge merges several <source> snapshots into one <destination> snapshot.
+Merge happens from left to right. Packages with the same name-architecture
+pair are replaced during merge (package from latest snapshot on the list
+wins). If run with only one source snapshot, merge copies <source> into
+<destination>.
+
+Example:
 
-ex.
     $ aptly snapshot merge wheezy-w-backports wheezy-main wheezy-backports
 `,
 		Flag: *flag.NewFlagSet("aptly-snapshot-merge", flag.ExitOnError),

cmd/snapshot_pull.go

@@ -170,14 +170,16 @@ func makeCmdSnapshotPull() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlySnapshotPull,
 		UsageLine: "pull <name> <source> <destination> <package-name> ...",
-		Short:     "performs partial upgrades (pulls new packages) from another snapshot",
+		Short:     "pull packages from another snapshot",
 		Long: `
-Command pull pulls new packages along with its dependencies in <name> snapshot
-from <source> snapshot. Also can upgrade package version from one snapshot into
-another, once again along with dependencies. New snapshot <destination> is created as result of this
-process. Packages could be specified simply as 'package-name' or as dependency 'package-name (>= version)'.
+Command pull pulls new packages along with its dependencies to snapshot <name>
+from snapshot <source>. Pull can upgrade package version in <name> with
+versions from <source> following dependencies. New snapshot <destination>
+is created as result of this process. Packages could be specified simply
+as 'package-name' or as dependency 'package-name (>= version)'.
+
+Example:
 
-ex.
     $ aptly snapshot pull wheezy-main wheezy-backports wheezy-new-xorg xorg-server-server
 `,
 		Flag: *flag.NewFlagSet("aptly-snapshot-pull", flag.ExitOnError),

cmd/snapshot_show.go

@@ -48,7 +48,8 @@ func makeCmdSnapshotShow() *commander.Command {
 		Long: `
 Command show displays full information about snapshot.
 
-ex.
+Example:
+
     $ aptly snapshot show wheezy-main
 `,
 		Flag: *flag.NewFlagSet("aptly-snapshot-show", flag.ExitOnError),

cmd/snapshot_verify.go

@@ -102,12 +102,14 @@ func makeCmdSnapshotVerify() *commander.Command {
 	cmd := &commander.Command{
 		Run:       aptlySnapshotVerify,
 		UsageLine: "verify <name> [<source> ...]",
-		Short:     "verifies that dependencies are satisfied in snapshot",
+		Short:     "verify dependencies in snapshot",
 		Long: `
-Verify does depenency resolution in snapshot, possibly using additional snapshots as dependency sources.
-All unsatisfied dependencies are returned.
+Verify does depenency resolution in snapshot <name>, possibly using additional
+snapshots <source> as dependency sources. All unsatisfied dependencies are
+printed.
+
+Example:
 
-ex.
     $ aptly snapshot verify wheezy-main wheezy-contrib wheezy-non-free
 `,
 		Flag: *flag.NewFlagSet("aptly-snapshot-verify", flag.ExitOnError),