From 21d1dbbb67b1ccefa8fbe249a3137083666516e5 Mon Sep 17 00:00:00 2001 From: Steffen Forkmann Date: Mon, 8 Dec 2014 12:04:17 +0100 Subject: [PATCH 1/4] Show command help on --help - relates to #433 --- .gitignore | 11 + Paket.sln | 13 +- RELEASE_NOTES.md | 10 +- docs/content/convert-from-nuget.md | 57 ----- docs/content/faq.md | 2 +- docs/content/index.md | 2 +- docs/content/paket-add.md | 35 --- docs/content/paket-find-refs.md | 32 --- docs/content/paket-init-auto-restore.md | 12 - docs/content/paket-init.md | 6 - docs/content/paket-install.md | 12 - docs/content/paket-outdated.md | 34 --- docs/content/paket-remove.md | 16 -- docs/content/paket-restore.md | 12 - docs/content/paket-simplify.md | 60 ----- docs/content/paket-update.md | 25 -- docs/tools/generate.fsx | 9 +- docs/tools/templates/template.cshtml | 2 +- src/Paket/HelpTexts.fs | 316 ++++++++++++++++++++++++ src/Paket/Paket.fsproj | 1 + src/Paket/Program.fs | 93 ++++--- 21 files changed, 400 insertions(+), 360 deletions(-) delete mode 100644 docs/content/convert-from-nuget.md delete mode 100644 docs/content/paket-add.md delete mode 100644 docs/content/paket-find-refs.md delete mode 100644 docs/content/paket-init-auto-restore.md delete mode 100644 docs/content/paket-init.md delete mode 100644 docs/content/paket-install.md delete mode 100644 docs/content/paket-outdated.md delete mode 100644 docs/content/paket-remove.md delete mode 100644 docs/content/paket-restore.md delete mode 100644 docs/content/paket-simplify.md delete mode 100644 docs/content/paket-update.md create mode 100644 src/Paket/HelpTexts.fs diff --git a/.gitignore b/.gitignore index 2cbb02907c..954197e229 100644 --- a/.gitignore +++ b/.gitignore @@ -186,3 +186,14 @@ paket-files docs/content/license.md docs/content/release-notes.md _NCrunch_Paket +docs/content/paket-init.md +docs/content/paket-add.md +docs/content/paket-find-refs.md +docs/content/paket-install.md +docs/content/paket-outdated.md +docs/content/paket-remove.md +docs/content/paket-update.md +docs/content/paket-convert-from-nuget.md.md +docs/content/paket-init-auto-restore.md +docs/content/paket-restore.md +docs/content/paket-simplify.md diff --git a/Paket.sln b/Paket.sln index fc471386b3..9e28e8382a 100644 --- a/Paket.sln +++ b/Paket.sln @@ -1,6 +1,6 @@ Microsoft Visual Studio Solution File, Format Version 12.00 # Visual Studio 2013 -VisualStudioVersion = 12.0.30723.0 +VisualStudioVersion = 12.0.31101.0 MinimumVisualStudioVersion = 10.0.40219.1 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{A6A6AF7D-D6E3-442D-9B1E-58CC91879BE1}" EndProject @@ -26,24 +26,13 @@ EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "content", "content", "{8E6D5255-776D-4B61-85F9-73C37AA1FB9A}" ProjectSection(SolutionItems) = preProject docs\content\bootstrapper.md = docs\content\bootstrapper.md - docs\content\convert-from-nuget.md = docs\content\convert-from-nuget.md docs\content\dependencies-file.md = docs\content\dependencies-file.md docs\content\faq.md = docs\content\faq.md docs\content\http-dependencies.md = docs\content\http-dependencies.md docs\content\index.md = docs\content\index.md docs\content\lock-file.md = docs\content\lock-file.md docs\content\nuget-dependencies.md = docs\content\nuget-dependencies.md - docs\content\paket-add.md = docs\content\paket-add.md docs\content\paket-config-file.md = docs\content\paket-config-file.md - docs\content\paket-find-refs.md = docs\content\paket-find-refs.md - docs\content\paket-init-auto-restore.md = docs\content\paket-init-auto-restore.md - docs\content\paket-init.md = docs\content\paket-init.md - docs\content\paket-install.md = docs\content\paket-install.md - docs\content\paket-outdated.md = docs\content\paket-outdated.md - docs\content\paket-remove.md = docs\content\paket-remove.md - docs\content\paket-restore.md = docs\content\paket-restore.md - docs\content\paket-simplify.md = docs\content\paket-simplify.md - docs\content\paket-update.md = docs\content\paket-update.md docs\content\paket.dependencies = docs\content\paket.dependencies docs\content\reference-from-repl.fsx = docs\content\reference-from-repl.fsx docs\content\references-files.md = docs\content\references-files.md diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index b53489c330..8afa4d907c 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -80,7 +80,7 @@ * New support for general HTTP dependencies - http://fsprojects.github.io/Paket/http-dependencies.html * New F# Interactive support - http://fsprojects.github.io/Paket/reference-from-repl.html * New `paket find-refs` command - http://fsprojects.github.io/Paket/paket-find-refs.html -* Migration of NuGet source credentials during `paket convert-from-nuget` - http://fsprojects.github.io/Paket/convert-from-nuget.html#Migrating-NuGet-source-credentials +* Migration of NuGet source credentials during `paket convert-from-nuget` - http://fsprojects.github.io/Paket/paket-convert-from-nuget.html#Migrating-NuGet-source-credentials * Bootstrapper uses .NET 4.0 - https://github.com/fsprojects/Paket/pull/355 * Adding --ignore-constraints to `paket outdated` - https://github.com/fsprojects/Paket/issues/308 * PERFORMANCE: If `paket add` doesn't change the `paket.dependencies` file then the resolver process will be skipped @@ -133,7 +133,7 @@ * More portable profiles - https://github.com/fsprojects/Paket/issues/281 * Added net11 to framework handling - https://github.com/fsprojects/Paket/pull/269 * Create references for Win8 - https://github.com/fsprojects/Paket/issues/280 -* Detect VS automatic nuget restore and create paket restore - http://fsprojects.github.io/Paket/convert-from-nuget.html#Automated-process +* Detect VS automatic nuget restore and create paket restore - http://fsprojects.github.io/Paket/paket-convert-from-nuget.html#Automated-process * `paket convert-from-nuget` doesn't duplicate paket solution items - https://github.com/fsprojects/Paket/pull/286 * BUGFIX: Paket removes old framework references if during install - https://github.com/fsprojects/Paket/issues/274 * BUGFIX: Don't let the bootstrapper fail if we already have a paket.exe @@ -184,7 +184,7 @@ * Use credentials from nuget.config on paket convert-from-nuget - https://github.com/fsprojects/Paket/issues/198 * Deploy fixed targets file - https://github.com/fsprojects/Paket/issues/172 * New [--pre] and [--strict] modes for paket outdated - http://fsprojects.github.io/Paket/paket-outdated.html -* New --no-auto-restore option for `convert-from-nuget` command - http://fsprojects.github.io/Paket/convert-from-nuget.html#Automated-process +* New --no-auto-restore option for `convert-from-nuget` command - http://fsprojects.github.io/Paket/paket-convert-from-nuget.html#Automated-process * Adding support for new portable profiles * paket.exe is now signed * Allow to reference .exe files from NuGet packages @@ -213,7 +213,7 @@ * Support for private NuGet feeds - http://fsprojects.github.io/Paket/nuget-dependencies.html#NuGet-feeds * New NuGet package version constraints - http://fsprojects.github.io/Paket/nuget-dependencies.html#Further-version-constraints * Respect case sensitivity for package paths for Linux - https://github.com/fsprojects/Paket/pull/137 -* Improved convert-from-nuget command - http://fsprojects.github.io/Paket/convert-from-nuget.html +* Improved convert-from-nuget command - http://fsprojects.github.io/Paket/paket-convert-from-nuget.html * New paket.bootstrapper.exe (7KB) allows to download paket.exe from github.com - http://fsprojects.github.io/Paket/paket-init-auto-restore.html * New package resolver algorithm * Better verbose mode - use -v flag @@ -225,7 +225,7 @@ #### 0.2.0 - 17.09.2014 * Allow to directly link GitHub files - http://fsprojects.github.io/Paket/http-dependencies.html -* Automatic NuGet conversion - http://fsprojects.github.io/Paket/convert-from-nuget.html +* Automatic NuGet conversion - http://fsprojects.github.io/Paket/paket-convert-from-nuget.html * Cleaner syntax in paket.dependencies - https://github.com/fsprojects/Paket/pull/95 * Strict mode - https://github.com/fsprojects/Paket/pull/104 * Detecting portable profiles diff --git a/docs/content/convert-from-nuget.md b/docs/content/convert-from-nuget.md deleted file mode 100644 index b172ef0bb5..0000000000 --- a/docs/content/convert-from-nuget.md +++ /dev/null @@ -1,57 +0,0 @@ -# Convert your solution from NuGet - -## Manual process - -If you are already using `NuGet.exe` for package restore then it should be easy to convert to Paket. - -1. Analyse your `packages.config` files and extract the referenced packages into a [`paket.dependencies` file](dependencies-file.html). -2. Convert each `packages.config` file to [`paket.references`](references-files.html) syntax. This is very easy - you just have to remove all the XML and keep the package names. -3. Run [paket install](paket-install.html) with the `--hard` flag. This will analyze the dependencies, generate a [`paket.lock` file](lock-file.html), remove all the old package references from your project files and replace them with equivalent `Reference`s in a syntax that can be managed automatically by Paket. - -
-## Automated process - -Paket can assist you with the conversion. The `paket convert-from-nuget` command: - -1. Finds all `packages.config` files, generates a [`paket.dependencies` file](dependencies-file.html) in the solution root and replaces each `packages.config` with an equivalent [`paket.references` file](references-files.html). -2. If there is a solution-level `packages.config`, then it will be removed and its dependencies will be included into the [`paket.dependencies`](dependencies-file.html). -3. If you use NuGet Package Restore ([MSBuild-Integrated or Automatic Visual Studio Package Restore](http://docs.nuget.org/docs/workflows/migrating-to-automatic-package-restore)), then the [`paket init-auto-restore`](paket-init-auto-restore.html) command will be invoked. -4. Next (unless `--no-install` is specified), the [paket install](paket-install.html) process with the `--hard` flag will be executed. This will: - - - analyze the dependencies. - - generate a [`paket.lock` file](lock-file.html). - - remove all the old package references from your project files and install new references in Paket's syntax. - -5. If you specify `--force`, the conversion will attempt to infer additional dependencies from newly added / previously unprocessed `packages.config` files and - - - add any newly discovered dependencies to the end of an existing `paket.dependencies` file. - - transfer/append references from the `packages.config` files into `paket.references` files alongside. - -
- - [lang=batchfile] - $ paket convert-from-nuget [--force] [--no-install] [--no-auto-restore] [--creds-migration MODE] - -Options: - - `--force`: Forces the conversion, even if a [`paket.dependencies` file](dependencies-file.html) or [`paket.references`](references-files.html) files are present. - - `--no-install`: Skips [`paket install --hard`](paket-install.html) process afterward generation of dependencies / references files. - - `--no-auto-restore`: Skips [`paket init-auto-restore`](paket-init-auto-restore.html) process afterward generation of dependencies / references files. - - `--creds-migration`: Specify mode for migrating NuGet source credentials. Possible values for `MODE` are [`encrypt`|`plaintext`|`selective`]. The default `MODE` is `encrypt`. - -## Migrating NuGet source credentials - -If you are using authorized NuGet feeds, convert-from-nuget command will automatically migrate the credentials for you. -Following are valid modes for `--creds-migration` option: - -1. `encrypt` - Encrypt your credentials and save in [Paket configuration file](paket-config-file.html). -2. `plaintext` - Include your credentials in plaintext in [`paket.dependencies`](dependencies-file.html) file. See [example](nuget-dependencies.html#plaintext-credentials) -3. `selective` - Use this switch, if you're using more than one authorized NuGet feed, and want to apply different mode for each of them. - -## Simplify direct dependencies - -After converting your solution from NuGet, you may end up with many indirect dependencies in your Paket files. -Consider using [`paket simplify`](paket-simplify.html) to remove unnecessary indirect dependencies from your [`paket.dependencies`](dependencies-file.html) and [`paket.references`](references-files.html) files. \ No newline at end of file diff --git a/docs/content/faq.md b/docs/content/faq.md index 11fbe7dea0..080c2f5a02 100644 --- a/docs/content/faq.md +++ b/docs/content/faq.md @@ -54,7 +54,7 @@ Instead we encourage the .NET community to use a declarative install process and ## I'm already using NuGet. How can I convert to Paket? -The process is very easy and you can read more about it in the [convert from NuGet](convert-from-nuget.html) section. +The process is very easy and you can read more about it in the [convert from NuGet](paket-convert-from-nuget.html) section. ## Why should I commit the lock file? diff --git a/docs/content/index.md b/docs/content/index.md index 18107923c7..5c6d7b58ba 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -2,7 +2,7 @@ Paket is a dependency manager for .NET and [Mono][mono] projects, which is designed to work well with [NuGet][nuget] packages and also enables [referencing files directly from GitHub repositories](http-dependencies.html). It enables precise and predictable control over what packages the projects within your application reference. More details are in the [FAQ](faq.html). -If you are already using NuGet for package restore in your solution then you can learn about the upgrade process in the [convert from NuGet](convert-from-nuget.html) section. +If you are already using NuGet for package restore in your solution then you can learn about the upgrade process in the [convert from NuGet](paket-convert-from-nuget.html) section. [mono]: http://www.mono-project.com/ [nuget]: https://www.nuget.org/ diff --git a/docs/content/paket-add.md b/docs/content/paket-add.md deleted file mode 100644 index 4912fff64c..0000000000 --- a/docs/content/paket-add.md +++ /dev/null @@ -1,35 +0,0 @@ -# paket add - -Adds a new package to your [`paket.dependencies` file](dependencies-file.html). - - [lang=batchfile] - $ paket add nuget PACKAGENAME [version VERSION] [--interactive] [--force] [--hard] - -Options: - - `--interactive`: Asks the user for every project if he or she wants to add the package to the projects's [`paket.references` file](references-file.html). - - `--force`: Forces the download and reinstallation of all packages. - - `--hard`: Replaces package references within project files even if they are not yet adhering to to Paket's conventions (and hence considered manually managed). See [convert from NuGet](convert-from-nuget.html). - - See also [paket remove](paket-remove.html). - -## Sample - -Consider the following [`paket.dependencies` file](dependencies-file.html): - - source https://nuget.org/api/v2 - - nuget FAKE - -Now we run `paket add nuget xunit --interactive` install the package: - -![alt text](img/interactive-add.png "Interactive paket add") - -This will add the package to the selected [`paket.references` files](references-file.html) and also to the [`paket.dependencies` file](dependencies-file.html): - - source https://nuget.org/api/v2 - - nuget FAKE - nuget xunit \ No newline at end of file diff --git a/docs/content/paket-find-refs.md b/docs/content/paket-find-refs.md deleted file mode 100644 index 474f932495..0000000000 --- a/docs/content/paket-find-refs.md +++ /dev/null @@ -1,32 +0,0 @@ -# paket find-refs - -Finds all project files that have the given NuGet packages installed. - - [lang=batchfile] - $ paket find-refs PACKAGENAME1 PACKAGENAME1 ... - -## Sample - -*.src/Paket/paket.references* contains: - - UnionArgParser - FSharp.Core - -*.src/Paket.Core/paket.references* contains: - - Newtonsoft.Json - DotNetZip - FSharp.Core - -Now we run - - paket find-refs DotNetZip FSharp.Core - -and paket gives the following output: - - DotNetZip - .src/Paket.Core/Paket.Core.fsproj - - FSharp.Core - .src/Paket.Core/Paket.Core.fsproj - .src/Paket/Paket.fsproj \ No newline at end of file diff --git a/docs/content/paket-init-auto-restore.md b/docs/content/paket-init-auto-restore.md deleted file mode 100644 index 7b38aaa5e1..0000000000 --- a/docs/content/paket-init-auto-restore.md +++ /dev/null @@ -1,12 +0,0 @@ -# paket init-auto-restore - -Enables automatic Package Restore in Visual Studio during the build process. - - [lang=batchfile] - $ paket init-auto-restore - -The command: - - - creates a `.paket` directory in your solution root - - downloads `paket.targets` and `paket.bootstrapper.exe` into it - - adds an `` statement for `paket.targets` to all projects under the working directory. \ No newline at end of file diff --git a/docs/content/paket-init.md b/docs/content/paket-init.md deleted file mode 100644 index 37031d0286..0000000000 --- a/docs/content/paket-init.md +++ /dev/null @@ -1,6 +0,0 @@ -# paket init - -Creates empty dependencies file in working directory. - - [lang=batchfile] - $ paket init \ No newline at end of file diff --git a/docs/content/paket-install.md b/docs/content/paket-install.md deleted file mode 100644 index 478dcc3a20..0000000000 --- a/docs/content/paket-install.md +++ /dev/null @@ -1,12 +0,0 @@ -# paket install - -Ensures that all dependencies in your [`paket.dependencies` file](dependencies-file.html) are present in the `packages` directory and referenced correctly in all projects. - - [lang=batchfile] - $ paket install [--force] [--hard] - -Options: - - `--force`: Forces the download and reinstallation of all packages. - - `--hard`: Replaces package references within project files even if they are not yet adhering to Paket's conventions (and hence considered manually managed). See [convert from NuGet](convert-from-nuget.html). diff --git a/docs/content/paket-outdated.md b/docs/content/paket-outdated.md deleted file mode 100644 index 5447aad04c..0000000000 --- a/docs/content/paket-outdated.md +++ /dev/null @@ -1,34 +0,0 @@ -# paket outdated - -Lists all dependencies that have newer versions available. - - [lang=batchfile] - $ paket outdated [--pre] [--ignore-constraints] - -Options: - - `--pre`: Includes prereleases. - - `--ignore-constraints`: Ignores the version requirement as in the [`paket.dependencies`](dependencies-file.html). - -## Sample - -Consider the following [`paket.dependencies` file](dependencies-file.html): - - source https://nuget.org/api/v2 - - nuget Castle.Core - nuget Castle.Windsor - -and the following [`paket.lock` file](lock-file.html): - - NUGET - remote: https://nuget.org/api/v2 - specs: - Castle.Core (2.0.0) - Castle.Windsor (2.0.0) - Castle.Core (>= 2.0.0) - -Now we run `paket outdated`: - -![alt text](img/paket-outdated.png "paket outdated command") \ No newline at end of file diff --git a/docs/content/paket-remove.md b/docs/content/paket-remove.md deleted file mode 100644 index 79ec0fdc9e..0000000000 --- a/docs/content/paket-remove.md +++ /dev/null @@ -1,16 +0,0 @@ -# paket remove - -Removes a package from your [`paket.dependencies` file](dependencies-file.html) and all [`paket.references` files](references-file.html). - - [lang=batchfile] - $ paket remove nuget PACKAGENAME [--interactive] [--force] [--hard] - -Options: - - `--interactive`: Asks the user for every project if he or she wants to remove the package from the projects's [`paket.references` file](references-file.html). By default every installation of the package is removed. - - `--force`: Forces the download and reinstallation of all packages. - - `--hard`: Replaces package references within project files even if they are not yet adhering to to Paket's conventions (and hence considered manually managed). See [convert from NuGet](convert-from-nuget.html). - -See also [paket add](paket-add.html). \ No newline at end of file diff --git a/docs/content/paket-restore.md b/docs/content/paket-restore.md deleted file mode 100644 index 48f97812d1..0000000000 --- a/docs/content/paket-restore.md +++ /dev/null @@ -1,12 +0,0 @@ -# paket restore - -Ensures that all dependencies in your [`paket.dependencies` file](dependencies-file.html) are present in the `packages` directory . - - [lang=batchfile] - $ paket restore [--force] [--references-files REFERENCESFILE1 REFERENCESFILE2 ...] - -Options: - - `--force`: Forces the download of all packages. - - `--references-files`: Allows to restore all packages from the given `paket.references` files. If no `paket.references` file is given then all packages will be restored. \ No newline at end of file diff --git a/docs/content/paket-simplify.md b/docs/content/paket-simplify.md deleted file mode 100644 index bc8bf3a182..0000000000 --- a/docs/content/paket-simplify.md +++ /dev/null @@ -1,60 +0,0 @@ -# paket simplify - -Simplifies your [`paket.dependencies` file](dependencies-file.html) by removing indirect dependencies. -Does also simplify [`paket.references` files](references-files.html), unless [strict](dependencies-file.html#Strict-references) mode is used. - - [lang=batchfile] - $ paket simplify [-v] [--interactive] - -Options: - - `-v`: Verbose - output the difference in content before and after running simplify command. - - `--interactive`: Asks to confirm to delete every indirect dependency from each of the files. See [Interactive Mode](paket-simplify.html#Interactive-mode). - -## Sample - -When you install `Castle.Windsor` package in NuGet to a project, it will generate a following `packages.config` file in the project location: - - [lang=xml] - - - - - - -After converting to Paket with [`paket convert-from-nuget command`](convert-from-nuget.html), you should get a following [`paket.dependencies` file](dependencies-file.html): - - source https://nuget.org/api/v2 - - nuget Castle.Core 3.3.1 - nuget Castle.Windsor 3.3.0 - -and the NuGet `packages.config` should be converted to following [`paket.references` file](references-files.html) : - - Castle.Core - Castle.Windsor - -As you have already probably guessed, the `Castle.Windsor` package happens to have a dependency on the `Castle.Core` package. -Paket by default (without [strict](dependencies-file.html#Strict-references) mode) adds references to all required dependencies of a package that you define for a specific project in [`paket.references` file](references-files.html). -In other words, you still get the same result if you remove `Castle.Core` from your [`paket.references` file](references-files.html). -And this is exactly what happens after executing `paket simplify` command: - - source https://nuget.org/api/v2 - - nuget Castle.Windsor 3.3.0 - -will be the content of your [`paket.dependencies` file](dependencies-file.html), and: - - Castle.Windsor - -will be the content of your [`paket.references` file](references-files.html). - -Unless you are relying heavily on components from `Castle.Core`, you would not care about controlling the required version of `Castle.Core` package. Paket will do the job. - -The simplify command will help you maintain your direct dependencies. - -## Interactive mode - -Sometimes, you may still want to have control over some of the indirect dependencies. In this case you can use the `--interactive` flag, -which will ask you to confirm before deleting a dependency from a file. diff --git a/docs/content/paket-update.md b/docs/content/paket-update.md deleted file mode 100644 index d0247dd86b..0000000000 --- a/docs/content/paket-update.md +++ /dev/null @@ -1,25 +0,0 @@ -# paket update - -Recomputes the dependency resolution, updates the [`paket.lock` file](lock-file.html) and propagates any resulting package changes into all project files referencing updated packages. - - [lang=batchfile] - $ paket update [--force] [--hard] - -Options: - - `--force`: Forces the download and reinstallation of all packages. - - `--hard`: Replaces package references within project files even if they are not yet adhering to to Paket's conventions (and hence considered manually managed). See [convert from NuGet](convert-from-nuget.html). - -## Updating a single package - -It's also possible to update only a single package and to keep all other dependencies fixed: - - [lang=batchfile] - $ paket update nuget PACKAGENAME [version VERSION] [--force] [--hard] - -Options: - - `--force`: Forces the download and reinstallation of all packages. - - `--hard`: Replaces package references within project files even if they are not yet adhering to to Paket's conventions (and hence considered manually managed). See [convert from NuGet](convert-from-nuget.html). \ No newline at end of file diff --git a/docs/tools/generate.fsx b/docs/tools/generate.fsx index 54a2c0c5a7..7f09eb5ea7 100644 --- a/docs/tools/generate.fsx +++ b/docs/tools/generate.fsx @@ -1,4 +1,11 @@ -// -------------------------------------------------------------------------------------- +/// Getting help docs from Paket.exe +#r "../../bin/Paket.exe" +open System.IO + +Paket.HelpTexts.commands +|> Seq.iter (fun kv -> File.WriteAllText(sprintf "../content/paket-%s.md" kv.Key,kv.Value)) + +// -------------------------------------------------------------------------------------- // Builds the documentation from `.fsx` and `.md` files in the 'docs/content' directory // (the generated documentation is stored in the 'docs/output' directory) // -------------------------------------------------------------------------------------- diff --git a/docs/tools/templates/template.cshtml b/docs/tools/templates/template.cshtml index 8ba169198e..41d40fc94f 100644 --- a/docs/tools/templates/template.cshtml +++ b/docs/tools/templates/template.cshtml @@ -69,7 +69,7 @@
  • paket outdated
  • paket simplify
    • -
  • paket convert-from-nuget
    • +
  • paket convert-from-nuget
  • paket init-auto-restore
  • paket find-refs
  • diff --git a/src/Paket/HelpTexts.fs b/src/Paket/HelpTexts.fs new file mode 100644 index 0000000000..70f46f35df --- /dev/null +++ b/src/Paket/HelpTexts.fs @@ -0,0 +1,316 @@ +module Paket.HelpTexts + +let commands = + ["convert-from-nuget.md", """# Convert your solution from NuGet + +## Manual process + +If you are already using `NuGet.exe` for package restore then it should be easy to convert to Paket. + +1. Analyse your `packages.config` files and extract the referenced packages into a [`paket.dependencies` file](dependencies-file.html). +2. Convert each `packages.config` file to [`paket.references`](references-files.html) syntax. This is very easy - you just have to remove all the XML and keep the package names. +3. Run [paket install](paket-install.html) with the `--hard` flag. This will analyze the dependencies, generate a [`paket.lock` file](lock-file.html), remove all the old package references from your project files and replace them with equivalent `Reference`s in a syntax that can be managed automatically by Paket. + +
    +## Automated process + +Paket can assist you with the conversion. The `paket convert-from-nuget` command: + +1. Finds all `packages.config` files, generates a [`paket.dependencies` file](dependencies-file.html) in the solution root and replaces each `packages.config` with an equivalent [`paket.references` file](references-files.html). +2. If there is a solution-level `packages.config`, then it will be removed and its dependencies will be included into the [`paket.dependencies`](dependencies-file.html). +3. If you use NuGet Package Restore ([MSBuild-Integrated or Automatic Visual Studio Package Restore](http://docs.nuget.org/docs/workflows/migrating-to-automatic-package-restore)), then the [`paket init-auto-restore`](paket-init-auto-restore.html) command will be invoked. +4. Next (unless `--no-install` is specified), the [paket install](paket-install.html) process with the `--hard` flag will be executed. This will: + + - analyze the dependencies. + - generate a [`paket.lock` file](lock-file.html). + - remove all the old package references from your project files and install new references in Paket's syntax. + +5. If you specify `--force`, the conversion will attempt to infer additional dependencies from newly added / previously unprocessed `packages.config` files and + + - add any newly discovered dependencies to the end of an existing `paket.dependencies` file. + - transfer/append references from the `packages.config` files into `paket.references` files alongside. + +
    + + [lang=batchfile] + $ paket convert-from-nuget [--force] [--no-install] [--no-auto-restore] [--creds-migration MODE] + +Options: + + `--force`: Forces the conversion, even if a [`paket.dependencies` file](dependencies-file.html) or [`paket.references`](references-files.html) files are present. + + `--no-install`: Skips [`paket install --hard`](paket-install.html) process afterward generation of dependencies / references files. + + `--no-auto-restore`: Skips [`paket init-auto-restore`](paket-init-auto-restore.html) process afterward generation of dependencies / references files. + + `--creds-migration`: Specify mode for migrating NuGet source credentials. Possible values for `MODE` are [`encrypt`|`plaintext`|`selective`]. The default `MODE` is `encrypt`. + +## Migrating NuGet source credentials + +If you are using authorized NuGet feeds, convert-from-nuget command will automatically migrate the credentials for you. +Following are valid modes for `--creds-migration` option: + +1. `encrypt` - Encrypt your credentials and save in [Paket configuration file](paket-config-file.html). +2. `plaintext` - Include your credentials in plaintext in [`paket.dependencies`](dependencies-file.html) file. See [example](nuget-dependencies.html#plaintext-credentials) +3. `selective` - Use this switch, if you're using more than one authorized NuGet feed, and want to apply different mode for each of them. + +## Simplify direct dependencies + +After converting your solution from NuGet, you may end up with many indirect dependencies in your Paket files. +Consider using [`paket simplify`](paket-simplify.html) to remove unnecessary indirect dependencies from your [`paket.dependencies`](dependencies-file.html) and [`paket.references`](references-files.html) files.""" + + "init-auto-restore", """# paket init-auto-restore + +Enables automatic Package Restore in Visual Studio during the build process. + + [lang=batchfile] + $ paket init-auto-restore + +The command: + + - creates a `.paket` directory in your solution root + - downloads `paket.targets` and `paket.bootstrapper.exe` into it + - adds an `` statement for `paket.targets` to all projects under the working directory.""" + + "restore", """# paket restore + +Ensures that all dependencies in your [`paket.dependencies` file](dependencies-file.html) are present in the `packages` directory . + + [lang=batchfile] + $ paket restore [--force] [--references-files REFERENCESFILE1 REFERENCESFILE2 ...] + +Options: + + `--force`: Forces the download of all packages. + + `--references-files`: Allows to restore all packages from the given `paket.references` files. If no `paket.references` file is given then all packages will be restored.""" + + "simplify", """# paket simplify + +Simplifies your [`paket.dependencies` file](dependencies-file.html) by removing indirect dependencies. +Does also simplify [`paket.references` files](references-files.html), unless [strict](dependencies-file.html#Strict-references) mode is used. + + [lang=batchfile] + $ paket simplify [-v] [--interactive] + +Options: + + `-v`: Verbose - output the difference in content before and after running simplify command. + + `--interactive`: Asks to confirm to delete every indirect dependency from each of the files. See [Interactive Mode](paket-simplify.html#Interactive-mode). + +## Sample + +When you install `Castle.Windsor` package in NuGet to a project, it will generate a following `packages.config` file in the project location: + + [lang=xml] + + + + + + +After converting to Paket with [`paket convert-from-nuget command`](paket-convert-from-nuget.html), you should get a following [`paket.dependencies` file](dependencies-file.html): + + source https://nuget.org/api/v2 + + nuget Castle.Core 3.3.1 + nuget Castle.Windsor 3.3.0 + +and the NuGet `packages.config` should be converted to following [`paket.references` file](references-files.html) : + + Castle.Core + Castle.Windsor + +As you have already probably guessed, the `Castle.Windsor` package happens to have a dependency on the `Castle.Core` package. +Paket by default (without [strict](dependencies-file.html#Strict-references) mode) adds references to all required dependencies of a package that you define for a specific project in [`paket.references` file](references-files.html). +In other words, you still get the same result if you remove `Castle.Core` from your [`paket.references` file](references-files.html). +And this is exactly what happens after executing `paket simplify` command: + + source https://nuget.org/api/v2 + + nuget Castle.Windsor 3.3.0 + +will be the content of your [`paket.dependencies` file](dependencies-file.html), and: + + Castle.Windsor + +will be the content of your [`paket.references` file](references-files.html). + +Unless you are relying heavily on components from `Castle.Core`, you would not care about controlling the required version of `Castle.Core` package. Paket will do the job. + +The simplify command will help you maintain your direct dependencies. + +## Interactive mode + +Sometimes, you may still want to have control over some of the indirect dependencies. In this case you can use the `--interactive` flag, +which will ask you to confirm before deleting a dependency from a file.""" + + "init", """# paket init + +Creates empty dependencies file in working directory. + + [lang=batchfile] + $ paket init""" + + "add", """# paket add + +Adds a new package to your [`paket.dependencies` file](dependencies-file.html). + + [lang=batchfile] + $ paket add nuget PACKAGENAME [version VERSION] [--interactive] [--force] [--hard] + +Options: + + `--interactive`: Asks the user for every project if he or she wants to add the package to the projects's [`paket.references` file](references-file.html). + + `--force`: Forces the download and reinstallation of all packages. + + `--hard`: Replaces package references within project files even if they are not yet adhering to to Paket's conventions (and hence considered manually managed). See [convert from NuGet](paket-convert-from-nuget.html). + + See also [paket remove](paket-remove.html). + +## Sample + +Consider the following [`paket.dependencies` file](dependencies-file.html): + + source https://nuget.org/api/v2 + + nuget FAKE + +Now we run `paket add nuget xunit --interactive` install the package: + +![alt text](img/interactive-add.png "Interactive paket add") + +This will add the package to the selected [`paket.references` files](references-file.html) and also to the [`paket.dependencies` file](dependencies-file.html): + + source https://nuget.org/api/v2 + + nuget FAKE + nuget xunit""" + + "find-refs", """# paket find-refs + +Finds all project files that have the given NuGet packages installed. + + [lang=batchfile] + $ paket find-refs PACKAGENAME1 PACKAGENAME1 ... + +## Sample + +*.src/Paket/paket.references* contains: + + UnionArgParser + FSharp.Core + +*.src/Paket.Core/paket.references* contains: + + Newtonsoft.Json + DotNetZip + FSharp.Core + +Now we run + + paket find-refs DotNetZip FSharp.Core + +and paket gives the following output: + + DotNetZip + .src/Paket.Core/Paket.Core.fsproj + + FSharp.Core + .src/Paket.Core/Paket.Core.fsproj + .src/Paket/Paket.fsproj""" + + "update", """# paket update + +Recomputes the dependency resolution, updates the [`paket.lock` file](lock-file.html) and propagates any resulting package changes into all project files referencing updated packages. + + [lang=batchfile] + $ paket update [--force] [--hard] + +Options: + + `--force`: Forces the download and reinstallation of all packages. + + `--hard`: Replaces package references within project files even if they are not yet adhering to to Paket's conventions (and hence considered manually managed). See [convert from NuGet](paket-convert-from-nuget.html). + +## Updating a single package + +It's also possible to update only a single package and to keep all other dependencies fixed: + + [lang=batchfile] + $ paket update nuget PACKAGENAME [version VERSION] [--force] [--hard] + +Options: + + `--force`: Forces the download and reinstallation of all packages. + + `--hard`: Replaces package references within project files even if they are not yet adhering to to Paket's conventions (and hence considered manually managed). See [convert from NuGet](paket-convert-from-nuget.html).""" + + "outdated", """# paket outdated + +Lists all dependencies that have newer versions available. + + [lang=batchfile] + $ paket outdated [--pre] [--ignore-constraints] + +Options: + + `--pre`: Includes prereleases. + + `--ignore-constraints`: Ignores the version requirement as in the [`paket.dependencies`](dependencies-file.html). + +## Sample + +Consider the following [`paket.dependencies` file](dependencies-file.html): + + source https://nuget.org/api/v2 + + nuget Castle.Core + nuget Castle.Windsor + +and the following [`paket.lock` file](lock-file.html): + + NUGET + remote: https://nuget.org/api/v2 + specs: + Castle.Core (2.0.0) + Castle.Windsor (2.0.0) + Castle.Core (>= 2.0.0) + +Now we run `paket outdated`: + +![alt text](img/paket-outdated.png "paket outdated command")""" + + "remove", """# paket remove + +Removes a package from your [`paket.dependencies` file](dependencies-file.html) and all [`paket.references` files](references-file.html). + + [lang=batchfile] + $ paket remove nuget PACKAGENAME [--interactive] [--force] [--hard] + +Options: + + `--interactive`: Asks the user for every project if he or she wants to remove the package from the projects's [`paket.references` file](references-file.html). By default every installation of the package is removed. + + `--force`: Forces the download and reinstallation of all packages. + + `--hard`: Replaces package references within project files even if they are not yet adhering to to Paket's conventions (and hence considered manually managed). See [convert from NuGet](paket-convert-from-nuget.html). + +See also [paket add](paket-add.html).""" + + "install", """# paket install + +Ensures that all dependencies in your [`paket.dependencies` file](dependencies-file.html) are present in the `packages` directory and referenced correctly in all projects. + + [lang=batchfile] + $ paket install [--force] [--hard] + +Options: + + `--force`: Forces the download and reinstallation of all packages. + + `--hard`: Replaces package references within project files even if they are not yet adhering to Paket's conventions (and hence considered manually managed). See [convert from NuGet](paket-convert-from-nuget.html)."""] + + |> dict \ No newline at end of file diff --git a/src/Paket/Paket.fsproj b/src/Paket/Paket.fsproj index 5ac3b4c5e9..2b2223cc4b 100644 --- a/src/Paket/Paket.fsproj +++ b/src/Paket/Paket.fsproj @@ -71,6 +71,7 @@ FSharp.Core.sigdata Always + diff --git a/src/Paket/Program.fs b/src/Paket/Program.fs index f0d26ba86d..c3225238ac 100644 --- a/src/Paket/Program.fs +++ b/src/Paket/Program.fs @@ -85,7 +85,7 @@ let parser = UnionArgParser.Create("USAGE: paket [add|remove|insta let results = try - let results = parser.Parse() + let results = parser.Parse(raiseOnUsage=false) let command = if results.Contains <@ CLIArguments.Init @> then Command.Init elif results.Contains <@ CLIArguments.Add @> then Command.Add @@ -116,47 +116,64 @@ try let hard = results.Contains <@ CLIArguments.Hard @> let noInstall = results.Contains <@ CLIArguments.No_Install @> let noAutoRestore = results.Contains <@ CLIArguments.No_Auto_Restore @> - let includePrereleases = results.Contains <@ CLIArguments.Include_Prereleases @> + let includePrereleases = results.Contains <@ CLIArguments.Include_Prereleases @> - match command with - | Command.Init -> Dependencies.Create() |> ignore - | Command.Add -> - let packageName = results.GetResult <@ CLIArguments.Nuget @> - let version = - match results.TryGetResult <@ CLIArguments.Version @> with - | Some x -> x - | _ -> "" + if results.IsUsageRequested then + let showHelp s = tracefn "%s" s + match command with + | Command.Init -> showHelp HelpTexts.commands.["init"] + | Command.Add -> showHelp HelpTexts.commands.["add"] + | Command.Remove -> showHelp HelpTexts.commands.["remove"] + | Command.Install -> showHelp HelpTexts.commands.["install"] + | Command.Restore -> showHelp HelpTexts.commands.["restore"] + | Command.Update -> showHelp HelpTexts.commands.["update"] + | Command.Outdated -> showHelp HelpTexts.commands.["outdated"] + | Command.InitAutoRestore -> showHelp HelpTexts.commands.["init-auto-restore"] + | Command.ConvertFromNuget -> showHelp HelpTexts.commands.["convert-from-nuget"] + | Command.Simplify -> showHelp HelpTexts.commands.["simplify"] + | Command.FindRefs -> showHelp HelpTexts.commands.["find-refs"] + | Command.Unknown -> traceErrorfn "no command given.%s" (parser.Usage()) - Dependencies.Locate().Add(packageName, version, force, hard, interactive, noInstall |> not) - | Command.Remove -> - let packageName = results.GetResult <@ CLIArguments.Nuget @> - Dependencies.Locate().Remove(packageName,force,hard,interactive,noInstall |> not) - | Command.Install -> Dependencies.Locate().Install(force,hard) - | Command.Restore -> - let files = results.GetResults <@ CLIArguments.References_Files @> - Dependencies.Locate().Restore(force,files) - | Command.Update -> - match results.TryGetResult <@ CLIArguments.Nuget @> with - | Some packageName -> - let version = results.TryGetResult <@ CLIArguments.Version @> - Dependencies.Locate().UpdatePackage(packageName, version, force, hard) - | _ -> Dependencies.Locate().Update(force,hard) - | Command.Outdated -> - let strict = results.Contains <@ CLIArguments.Ignore_Constraints @> |> not - Dependencies.Locate().ShowOutdated(strict,includePrereleases) - | Command.InitAutoRestore -> Dependencies.Locate().InitAutoRestore() - | Command.ConvertFromNuget -> - let credsMigrationMode = results.TryGetResult <@ CLIArguments.Creds_Migration @> - Dependencies.ConvertFromNuget(force, noInstall |> not, noAutoRestore |> not, credsMigrationMode) - | Command.Simplify -> Dependencies.Locate().Simplify(interactive) - | Command.FindRefs -> - let packages = results.GetResults <@ CLIArguments.FindRefs @> - Dependencies.Locate().ShowReferencesFor(packages) - | Command.Unknown -> traceErrorfn "no command given.%s" (parser.Usage()) + else + match command with + | Command.Init -> Dependencies.Create() |> ignore + | Command.Add -> + let packageName = results.GetResult <@ CLIArguments.Nuget @> + let version = + match results.TryGetResult <@ CLIArguments.Version @> with + | Some x -> x + | _ -> "" + + Dependencies.Locate().Add(packageName, version, force, hard, interactive, noInstall |> not) + | Command.Remove -> + let packageName = results.GetResult <@ CLIArguments.Nuget @> + Dependencies.Locate().Remove(packageName,force,hard,interactive,noInstall |> not) + | Command.Install -> Dependencies.Locate().Install(force,hard) + | Command.Restore -> + let files = results.GetResults <@ CLIArguments.References_Files @> + Dependencies.Locate().Restore(force,files) + | Command.Update -> + match results.TryGetResult <@ CLIArguments.Nuget @> with + | Some packageName -> + let version = results.TryGetResult <@ CLIArguments.Version @> + Dependencies.Locate().UpdatePackage(packageName, version, force, hard) + | _ -> Dependencies.Locate().Update(force,hard) + | Command.Outdated -> + let strict = results.Contains <@ CLIArguments.Ignore_Constraints @> |> not + Dependencies.Locate().ShowOutdated(strict,includePrereleases) + | Command.InitAutoRestore -> Dependencies.Locate().InitAutoRestore() + | Command.ConvertFromNuget -> + let credsMigrationMode = results.TryGetResult <@ CLIArguments.Creds_Migration @> + Dependencies.ConvertFromNuget(force, noInstall |> not, noAutoRestore |> not, credsMigrationMode) + | Command.Simplify -> Dependencies.Locate().Simplify(interactive) + | Command.FindRefs -> + let packages = results.GetResults <@ CLIArguments.FindRefs @> + Dependencies.Locate().ShowReferencesFor(packages) + | Command.Unknown -> traceErrorfn "no command given.%s" (parser.Usage()) - let elapsedTime = Utils.TimeSpanToReadableString stopWatch.Elapsed + let elapsedTime = Utils.TimeSpanToReadableString stopWatch.Elapsed - tracefn "%s - ready." elapsedTime + tracefn "%s - ready." elapsedTime | None -> () with | exn -> From cac17677b4e9139acd1e2f96ba178fe6b2d2e6c3 Mon Sep 17 00:00:00 2001 From: Steffen Forkmann Date: Mon, 8 Dec 2014 17:41:40 +0100 Subject: [PATCH 2/4] fix typo --- src/Paket/HelpTexts.fs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Paket/HelpTexts.fs b/src/Paket/HelpTexts.fs index 70f46f35df..2829e66b0e 100644 --- a/src/Paket/HelpTexts.fs +++ b/src/Paket/HelpTexts.fs @@ -1,7 +1,7 @@ module Paket.HelpTexts let commands = - ["convert-from-nuget.md", """# Convert your solution from NuGet + ["convert-from-nuget", """# Convert your solution from NuGet ## Manual process From bad11f7fd52f273e0815b31f345834652125e088 Mon Sep 17 00:00:00 2001 From: Steffen Forkmann Date: Mon, 8 Dec 2014 18:42:10 +0100 Subject: [PATCH 3/4] Starting to refactor the command help into records - references #433 --- docs/tools/generate.fsx | 2 +- src/Paket/HelpTexts.fs | 96 ++++++++++++++++++++++------------------- src/Paket/Program.fs | 5 ++- 3 files changed, 56 insertions(+), 47 deletions(-) diff --git a/docs/tools/generate.fsx b/docs/tools/generate.fsx index 7f09eb5ea7..61ae0d5167 100644 --- a/docs/tools/generate.fsx +++ b/docs/tools/generate.fsx @@ -3,7 +3,7 @@ open System.IO Paket.HelpTexts.commands -|> Seq.iter (fun kv -> File.WriteAllText(sprintf "../content/paket-%s.md" kv.Key,kv.Value)) +|> Seq.iter (fun kv -> File.WriteAllText(sprintf "../content/paket-%s.md" kv.Key,kv.Value.ToMarkDown())) // -------------------------------------------------------------------------------------- // Builds the documentation from `.fsx` and `.md` files in the 'docs/content' directory diff --git a/src/Paket/HelpTexts.fs b/src/Paket/HelpTexts.fs index 2829e66b0e..c4422cb848 100644 --- a/src/Paket/HelpTexts.fs +++ b/src/Paket/HelpTexts.fs @@ -1,9 +1,15 @@ module Paket.HelpTexts -let commands = - ["convert-from-nuget", """# Convert your solution from NuGet +type CommandHelpTopic = + { Title : string + Text : string } + member this.ToMarkDown() = + sprintf "# %s%s%s" this.Title System.Environment.NewLine this.Text -## Manual process +let commands = + ["convert-from-nuget", + { Title = "Convert your solution from NuGet" + Text = """## Manual process If you are already using `NuGet.exe` for package restore then it should be easy to convert to Paket. @@ -57,11 +63,11 @@ Following are valid modes for `--creds-migration` option: ## Simplify direct dependencies After converting your solution from NuGet, you may end up with many indirect dependencies in your Paket files. -Consider using [`paket simplify`](paket-simplify.html) to remove unnecessary indirect dependencies from your [`paket.dependencies`](dependencies-file.html) and [`paket.references`](references-files.html) files.""" - - "init-auto-restore", """# paket init-auto-restore +Consider using [`paket simplify`](paket-simplify.html) to remove unnecessary indirect dependencies from your [`paket.dependencies`](dependencies-file.html) and [`paket.references`](references-files.html) files."""} -Enables automatic Package Restore in Visual Studio during the build process. + "init-auto-restore", + { Title = "paket init-auto-restore" + Text = """Enables automatic Package Restore in Visual Studio during the build process. [lang=batchfile] $ paket init-auto-restore @@ -70,11 +76,11 @@ The command: - creates a `.paket` directory in your solution root - downloads `paket.targets` and `paket.bootstrapper.exe` into it - - adds an `` statement for `paket.targets` to all projects under the working directory.""" + - adds an `` statement for `paket.targets` to all projects under the working directory."""} - "restore", """# paket restore - -Ensures that all dependencies in your [`paket.dependencies` file](dependencies-file.html) are present in the `packages` directory . + "restore", + { Title = "paket restore" + Text = """Ensures that all dependencies in your [`paket.dependencies` file](dependencies-file.html) are present in the `packages` directory . [lang=batchfile] $ paket restore [--force] [--references-files REFERENCESFILE1 REFERENCESFILE2 ...] @@ -83,11 +89,11 @@ Options: `--force`: Forces the download of all packages. - `--references-files`: Allows to restore all packages from the given `paket.references` files. If no `paket.references` file is given then all packages will be restored.""" - - "simplify", """# paket simplify + `--references-files`: Allows to restore all packages from the given `paket.references` files. If no `paket.references` file is given then all packages will be restored."""} -Simplifies your [`paket.dependencies` file](dependencies-file.html) by removing indirect dependencies. + "simplify", + { Title = "paket simplify" + Text = """Simplifies your [`paket.dependencies` file](dependencies-file.html) by removing indirect dependencies. Does also simplify [`paket.references` files](references-files.html), unless [strict](dependencies-file.html#Strict-references) mode is used. [lang=batchfile] @@ -117,7 +123,7 @@ After converting to Paket with [`paket convert-from-nuget command`](paket-conver nuget Castle.Core 3.3.1 nuget Castle.Windsor 3.3.0 -and the NuGet `packages.config` should be converted to following [`paket.references` file](references-files.html) : +and the NuGet `packages.config` should be converted to following [`paket.references` file](references-files.html): Castle.Core Castle.Windsor @@ -144,18 +150,18 @@ The simplify command will help you maintain your direct dependencies. ## Interactive mode Sometimes, you may still want to have control over some of the indirect dependencies. In this case you can use the `--interactive` flag, -which will ask you to confirm before deleting a dependency from a file.""" - - "init", """# paket init +which will ask you to confirm before deleting a dependency from a file."""} -Creates empty dependencies file in working directory. + "init", + { Title = "paket init" + Text = """Creates empty dependencies file in working directory. [lang=batchfile] - $ paket init""" + $ paket init"""} - "add", """# paket add - -Adds a new package to your [`paket.dependencies` file](dependencies-file.html). + "add", + { Title = "paket add" + Text = """Adds a new package to your [`paket.dependencies` file](dependencies-file.html). [lang=batchfile] $ paket add nuget PACKAGENAME [version VERSION] [--interactive] [--force] [--hard] @@ -187,11 +193,11 @@ This will add the package to the selected [`paket.references` files](references- source https://nuget.org/api/v2 nuget FAKE - nuget xunit""" - - "find-refs", """# paket find-refs + nuget xunit"""} -Finds all project files that have the given NuGet packages installed. + "find-refs", + { Title = "paket find-refs" + Text = """Finds all project files that have the given NuGet packages installed. [lang=batchfile] $ paket find-refs PACKAGENAME1 PACKAGENAME1 ... @@ -220,11 +226,11 @@ and paket gives the following output: FSharp.Core .src/Paket.Core/Paket.Core.fsproj - .src/Paket/Paket.fsproj""" - - "update", """# paket update + .src/Paket/Paket.fsproj"""} -Recomputes the dependency resolution, updates the [`paket.lock` file](lock-file.html) and propagates any resulting package changes into all project files referencing updated packages. + "update", + { Title = "paket update" + Text = """Recomputes the dependency resolution, updates the [`paket.lock` file](lock-file.html) and propagates any resulting package changes into all project files referencing updated packages. [lang=batchfile] $ paket update [--force] [--hard] @@ -246,11 +252,11 @@ Options: `--force`: Forces the download and reinstallation of all packages. - `--hard`: Replaces package references within project files even if they are not yet adhering to to Paket's conventions (and hence considered manually managed). See [convert from NuGet](paket-convert-from-nuget.html).""" + `--hard`: Replaces package references within project files even if they are not yet adhering to to Paket's conventions (and hence considered manually managed). See [convert from NuGet](paket-convert-from-nuget.html)."""} - "outdated", """# paket outdated - -Lists all dependencies that have newer versions available. + "outdated", + { Title = "paket outdated" + Text = """Lists all dependencies that have newer versions available. [lang=batchfile] $ paket outdated [--pre] [--ignore-constraints] @@ -281,11 +287,11 @@ and the following [`paket.lock` file](lock-file.html): Now we run `paket outdated`: -![alt text](img/paket-outdated.png "paket outdated command")""" - - "remove", """# paket remove +![alt text](img/paket-outdated.png "paket outdated command")"""} -Removes a package from your [`paket.dependencies` file](dependencies-file.html) and all [`paket.references` files](references-file.html). + "remove", + { Title = "paket remove" + Text = """Removes a package from your [`paket.dependencies` file](dependencies-file.html) and all [`paket.references` files](references-file.html). [lang=batchfile] $ paket remove nuget PACKAGENAME [--interactive] [--force] [--hard] @@ -298,11 +304,11 @@ Options: `--hard`: Replaces package references within project files even if they are not yet adhering to to Paket's conventions (and hence considered manually managed). See [convert from NuGet](paket-convert-from-nuget.html). -See also [paket add](paket-add.html).""" - - "install", """# paket install +See also [paket add](paket-add.html)."""} -Ensures that all dependencies in your [`paket.dependencies` file](dependencies-file.html) are present in the `packages` directory and referenced correctly in all projects. + "install", + { Title = "paket install" + Text = """Ensures that all dependencies in your [`paket.dependencies` file](dependencies-file.html) are present in the `packages` directory and referenced correctly in all projects. [lang=batchfile] $ paket install [--force] [--hard] @@ -311,6 +317,6 @@ Options: `--force`: Forces the download and reinstallation of all packages. - `--hard`: Replaces package references within project files even if they are not yet adhering to Paket's conventions (and hence considered manually managed). See [convert from NuGet](paket-convert-from-nuget.html)."""] + `--hard`: Replaces package references within project files even if they are not yet adhering to Paket's conventions (and hence considered manually managed). See [convert from NuGet](paket-convert-from-nuget.html)."""}] |> dict \ No newline at end of file diff --git a/src/Paket/Program.fs b/src/Paket/Program.fs index c3225238ac..222bd5c0f0 100644 --- a/src/Paket/Program.fs +++ b/src/Paket/Program.fs @@ -119,7 +119,10 @@ try let includePrereleases = results.Contains <@ CLIArguments.Include_Prereleases @> if results.IsUsageRequested then - let showHelp s = tracefn "%s" s + let showHelp (helpTopic:HelpTexts.CommandHelpTopic) = + tracefn "%s" helpTopic.Title + tracefn "%s" helpTopic.Text + match command with | Command.Init -> showHelp HelpTexts.commands.["init"] | Command.Add -> showHelp HelpTexts.commands.["add"] From bb00796dafcc7f6a2a89d1db9331663cbb324119 Mon Sep 17 00:00:00 2001 From: Steffen Forkmann Date: Tue, 9 Dec 2014 11:49:12 +0100 Subject: [PATCH 4/4] Use replacements to simplify help contents --- .gitignore | 1 + src/Paket/HelpTexts.fs | 73 +++++++++++++++++++++++------------------- 2 files changed, 41 insertions(+), 33 deletions(-) diff --git a/.gitignore b/.gitignore index 954197e229..b34ccc1a37 100644 --- a/.gitignore +++ b/.gitignore @@ -197,3 +197,4 @@ docs/content/paket-convert-from-nuget.md.md docs/content/paket-init-auto-restore.md docs/content/paket-restore.md docs/content/paket-simplify.md +docs/content/paket-convert-from-nuget.md diff --git a/src/Paket/HelpTexts.fs b/src/Paket/HelpTexts.fs index c4422cb848..8b427464ed 100644 --- a/src/Paket/HelpTexts.fs +++ b/src/Paket/HelpTexts.fs @@ -4,7 +4,14 @@ type CommandHelpTopic = { Title : string Text : string } member this.ToMarkDown() = - sprintf "# %s%s%s" this.Title System.Environment.NewLine this.Text + let text = + this.Text + .Replace("paket.dependencies file","[`paket.dependencies` file](dependencies-file.html)") + .Replace("paket.lock file","[`paket.lock` file](lock-file.html)") + .Replace("paket.references files","[`paket.references` files](references-files.html)") + .Replace("paket.references file","[`paket.references` file](references-files.html)") + + sprintf "# %s%s%s" this.Title System.Environment.NewLine text let commands = ["convert-from-nuget", @@ -13,22 +20,22 @@ let commands = If you are already using `NuGet.exe` for package restore then it should be easy to convert to Paket. -1. Analyse your `packages.config` files and extract the referenced packages into a [`paket.dependencies` file](dependencies-file.html). -2. Convert each `packages.config` file to [`paket.references`](references-files.html) syntax. This is very easy - you just have to remove all the XML and keep the package names. -3. Run [paket install](paket-install.html) with the `--hard` flag. This will analyze the dependencies, generate a [`paket.lock` file](lock-file.html), remove all the old package references from your project files and replace them with equivalent `Reference`s in a syntax that can be managed automatically by Paket. +1. Analyse your `packages.config` files and extract the referenced packages into a paket.dependencies file. +2. Convert each `packages.config` file to a paket.references file. This is very easy - you just have to remove all the XML and keep the package names. +3. Run [paket install](paket-install.html) with the `--hard` flag. This will analyze the dependencies, generate a paket.lock file, remove all the old package references from your project files and replace them with equivalent `Reference`s in a syntax that can be managed automatically by Paket.
    ## Automated process Paket can assist you with the conversion. The `paket convert-from-nuget` command: -1. Finds all `packages.config` files, generates a [`paket.dependencies` file](dependencies-file.html) in the solution root and replaces each `packages.config` with an equivalent [`paket.references` file](references-files.html). -2. If there is a solution-level `packages.config`, then it will be removed and its dependencies will be included into the [`paket.dependencies`](dependencies-file.html). +1. Finds all `packages.config` files, generates a paket.dependencies file in the solution root and replaces each `packages.config` with an equivalent paket.references file. +2. If there is a solution-level `packages.config`, then it will be removed and its dependencies will be included into the paket.dependencies file. 3. If you use NuGet Package Restore ([MSBuild-Integrated or Automatic Visual Studio Package Restore](http://docs.nuget.org/docs/workflows/migrating-to-automatic-package-restore)), then the [`paket init-auto-restore`](paket-init-auto-restore.html) command will be invoked. 4. Next (unless `--no-install` is specified), the [paket install](paket-install.html) process with the `--hard` flag will be executed. This will: - analyze the dependencies. - - generate a [`paket.lock` file](lock-file.html). + - generate a paket.lock file. - remove all the old package references from your project files and install new references in Paket's syntax. 5. If you specify `--force`, the conversion will attempt to infer additional dependencies from newly added / previously unprocessed `packages.config` files and @@ -43,7 +50,7 @@ Paket can assist you with the conversion. The `paket convert-from-nuget` command Options: - `--force`: Forces the conversion, even if a [`paket.dependencies` file](dependencies-file.html) or [`paket.references`](references-files.html) files are present. + `--force`: Forces the conversion, even if a paket.dependencies file or paket.references files are present. `--no-install`: Skips [`paket install --hard`](paket-install.html) process afterward generation of dependencies / references files. @@ -56,14 +63,14 @@ Options: If you are using authorized NuGet feeds, convert-from-nuget command will automatically migrate the credentials for you. Following are valid modes for `--creds-migration` option: -1. `encrypt` - Encrypt your credentials and save in [Paket configuration file](paket-config-file.html). -2. `plaintext` - Include your credentials in plaintext in [`paket.dependencies`](dependencies-file.html) file. See [example](nuget-dependencies.html#plaintext-credentials) +1. `encrypt` - Encrypt your credentials and save in [paket configuration file](paket-config-file.html). +2. `plaintext` - Include your credentials in plaintext in paket.dependencies file. See [example](nuget-dependencies.html#plaintext-credentials) 3. `selective` - Use this switch, if you're using more than one authorized NuGet feed, and want to apply different mode for each of them. ## Simplify direct dependencies After converting your solution from NuGet, you may end up with many indirect dependencies in your Paket files. -Consider using [`paket simplify`](paket-simplify.html) to remove unnecessary indirect dependencies from your [`paket.dependencies`](dependencies-file.html) and [`paket.references`](references-files.html) files."""} +Consider using [`paket simplify`](paket-simplify.html) to remove unnecessary indirect dependencies from your paket.dependencies file and paket.references files."""} "init-auto-restore", { Title = "paket init-auto-restore" @@ -80,7 +87,7 @@ The command: "restore", { Title = "paket restore" - Text = """Ensures that all dependencies in your [`paket.dependencies` file](dependencies-file.html) are present in the `packages` directory . + Text = """Ensures that all dependencies in your paket.dependencies file are present in the `packages` directory . [lang=batchfile] $ paket restore [--force] [--references-files REFERENCESFILE1 REFERENCESFILE2 ...] @@ -89,12 +96,12 @@ Options: `--force`: Forces the download of all packages. - `--references-files`: Allows to restore all packages from the given `paket.references` files. If no `paket.references` file is given then all packages will be restored."""} + `--references-files`: Allows to restore all packages from the given paket.references files. If no paket.references file is given then all packages will be restored."""} "simplify", { Title = "paket simplify" - Text = """Simplifies your [`paket.dependencies` file](dependencies-file.html) by removing indirect dependencies. -Does also simplify [`paket.references` files](references-files.html), unless [strict](dependencies-file.html#Strict-references) mode is used. + Text = """Simplifies your paket.dependencies file by removing indirect dependencies. +Does also simplify paket.references files, unless [strict](dependencies-file.html#Strict-references) mode is used. [lang=batchfile] $ paket simplify [-v] [--interactive] @@ -116,32 +123,32 @@ When you install `Castle.Windsor` package in NuGet to a project, it will generat -After converting to Paket with [`paket convert-from-nuget command`](paket-convert-from-nuget.html), you should get a following [`paket.dependencies` file](dependencies-file.html): +After converting to Paket with [`paket convert-from-nuget command`](paket-convert-from-nuget.html), you should get a following paket.dependencies file: source https://nuget.org/api/v2 nuget Castle.Core 3.3.1 nuget Castle.Windsor 3.3.0 -and the NuGet `packages.config` should be converted to following [`paket.references` file](references-files.html): +and the NuGet `packages.config` should be converted to following paket.references file: Castle.Core Castle.Windsor As you have already probably guessed, the `Castle.Windsor` package happens to have a dependency on the `Castle.Core` package. -Paket by default (without [strict](dependencies-file.html#Strict-references) mode) adds references to all required dependencies of a package that you define for a specific project in [`paket.references` file](references-files.html). -In other words, you still get the same result if you remove `Castle.Core` from your [`paket.references` file](references-files.html). +Paket by default (without [strict](dependencies-file.html#Strict-references) mode) adds references to all required dependencies of a package that you define for a specific project in paket.references file. +In other words, you still get the same result if you remove `Castle.Core` from your paket.references file. And this is exactly what happens after executing `paket simplify` command: source https://nuget.org/api/v2 nuget Castle.Windsor 3.3.0 -will be the content of your [`paket.dependencies` file](dependencies-file.html), and: +will be the content of your paket.dependencies file, and: Castle.Windsor -will be the content of your [`paket.references` file](references-files.html). +will be the content of your paket.references file. Unless you are relying heavily on components from `Castle.Core`, you would not care about controlling the required version of `Castle.Core` package. Paket will do the job. @@ -154,21 +161,21 @@ which will ask you to confirm before deleting a dependency from a file."""} "init", { Title = "paket init" - Text = """Creates empty dependencies file in working directory. + Text = """Creates empty paket.dependencies file in the working directory. [lang=batchfile] $ paket init"""} "add", { Title = "paket add" - Text = """Adds a new package to your [`paket.dependencies` file](dependencies-file.html). + Text = """Adds a new package to your paket.dependencies file. [lang=batchfile] $ paket add nuget PACKAGENAME [version VERSION] [--interactive] [--force] [--hard] Options: - `--interactive`: Asks the user for every project if he or she wants to add the package to the projects's [`paket.references` file](references-file.html). + `--interactive`: Asks the user for every project if he or she wants to add the package to the projects's paket.references file. `--force`: Forces the download and reinstallation of all packages. @@ -178,7 +185,7 @@ Options: ## Sample -Consider the following [`paket.dependencies` file](dependencies-file.html): +Consider the following paket.dependencies file: source https://nuget.org/api/v2 @@ -188,7 +195,7 @@ Now we run `paket add nuget xunit --interactive` install the package: ![alt text](img/interactive-add.png "Interactive paket add") -This will add the package to the selected [`paket.references` files](references-file.html) and also to the [`paket.dependencies` file](dependencies-file.html): +This will add the package to the selected paket.references files and also to the paket.dependencies file: source https://nuget.org/api/v2 @@ -230,7 +237,7 @@ and paket gives the following output: "update", { Title = "paket update" - Text = """Recomputes the dependency resolution, updates the [`paket.lock` file](lock-file.html) and propagates any resulting package changes into all project files referencing updated packages. + Text = """Recomputes the dependency resolution, updates the paket.lock file and propagates any resulting package changes into all project files referencing updated packages. [lang=batchfile] $ paket update [--force] [--hard] @@ -265,18 +272,18 @@ Options: `--pre`: Includes prereleases. - `--ignore-constraints`: Ignores the version requirement as in the [`paket.dependencies`](dependencies-file.html). + `--ignore-constraints`: Ignores the version requirement as in the paket.dependencies file. ## Sample -Consider the following [`paket.dependencies` file](dependencies-file.html): +Consider the following paket.dependencies file: source https://nuget.org/api/v2 nuget Castle.Core nuget Castle.Windsor -and the following [`paket.lock` file](lock-file.html): +and the following paket.lock file: NUGET remote: https://nuget.org/api/v2 @@ -291,14 +298,14 @@ Now we run `paket outdated`: "remove", { Title = "paket remove" - Text = """Removes a package from your [`paket.dependencies` file](dependencies-file.html) and all [`paket.references` files](references-file.html). + Text = """Removes a package from your paket.dependencies file and all paket.references files. [lang=batchfile] $ paket remove nuget PACKAGENAME [--interactive] [--force] [--hard] Options: - `--interactive`: Asks the user for every project if he or she wants to remove the package from the projects's [`paket.references` file](references-file.html). By default every installation of the package is removed. + `--interactive`: Asks the user for every project if he or she wants to remove the package from the projects's paket.references file. By default every installation of the package is removed. `--force`: Forces the download and reinstallation of all packages. @@ -308,7 +315,7 @@ See also [paket add](paket-add.html)."""} "install", { Title = "paket install" - Text = """Ensures that all dependencies in your [`paket.dependencies` file](dependencies-file.html) are present in the `packages` directory and referenced correctly in all projects. + Text = """Ensures that all dependencies in your paket.dependencies file are present in the `packages` directory and referenced correctly in all projects. [lang=batchfile] $ paket install [--force] [--hard]