Confusion between "paket install" and "paket update"

There’s considerable overlap in the behavior of paket install and paket update, and some confusion on which one should be used in which situation.

Summary

• paket update could also be called paket forget-everything-and-re-resolve (and-install-into-projects)
• paket install could also be called paket only-update-packages-where-absolutely-necessary (and-install-into-projects)

Proposed solution: My intuition is that paket install should really be called paket update --pin-unchanged, because this is what it really does.

paket install does not really have a purpose anymore then, but should probably be kept for compatibility reasons. The documentation of paket install could then say: “paket install has the same effect as paket update --pin-unchanged”. This would also remove the confusion between the two commands.

For completeness: The third use case (no updates to paket.lock) is already covered by another command:

• paket restore could also be called paket do-not-update-versions-and-install-into-projects

Details:

Behavior of paket update:

1. Delete paket.lock if it exists, therefore discarding the currently used versions of the packages (UpdateProcess.Update).
2. Compute a new paket.lock file based on paket.dependencies (UpdateProcess.SmartInstall/.SelectiveUpdate)
3. (Optionally:) Install everything from paket.lock (InstallProcess.InstallIntoProjects)

Behavior of paket install:

1. If no paket.lock file exists: Same behavior as paket update (it just calls UpdateProcess. SmartInstall)
2. If a paket.lock file exists: (UpdateProcess.SmartInstall/.SelectiveUpdate)
   1. Compare paket.lock and paket.dependencies to find (DependencyChangeDetection. findChangesInDependenciesFile):
      • Dependencies that were added to paket.dependencies
      • Dependencies where the current version from paket.lock does not match the version requirement from paket.dependencies
   2. Pin all unchanged dependencies (i.e. the ones that are not newly added or modified)
   3. Compute a new paket.lock, taking into account the pinned dependencies.
3. Install everything from paket.lock (InstallProcess.InstallIntoProjects)

Behavior of paket restore:

1. Install everything from paket.lock (RestoreProcess.Restore)

[cr7pt0gr4ph7]

Your’re right; I cross-checked RestoreProcess.Restore to verify this.

I incorporated your feedback into my proposal above. The original text is marked using strikethrough. Do you think it’s better now?

---

To get the terminology clear (and to try to establish an ubiquituous language):

Explanation: The relevant parts for the vocabulary are marked in bold.

• “What the docs say” contains the wording for Paket’s documentation.
• “What is meant” contains the operations that actually take place.
• “Verb” contains the command for paket (e.g. paket add) that realizes the domain operation from the first column.

What the docs say:	What is meant:	Verb
Add/Install a package	Add the package to paket.dependencies (and paket.references), update paket.lock as necessary, download the package and update the project files.	add
???	Add the package to paket.dependencies (and paket.references) and update paket.lock.	add --no-install
Install all packages	Update paket.lock as necessary, download all packages and update the project files.	install
Remove/Uninstall a package	Remove the package from paket.dependencies (and paket.references), update paket.lock as necessary, delete the downloaded files and update the project files.	remove
???	Remove the package from paket.dependencies (and paket.references) and update paket.lock as necessary.	remove --no-install
Update one or all packages	Look for new versions of a single/all packages and write them into paket.lock (and download/install them if not told otherwise).	update
Download the packages	Download the .nupkg files into packages/ but do nothing else.	restore
Update (the) project/s files	Update the project files with the current DLL paths (and download them according to paket.lock if necessary).	(install)

What’s your feedback on the table above? Does it match the “mental model” of the expected end user?

[forki]

we will review on the PR again - and discuss wording