Repository: conan-io/conan
Pull request: Improve '--update' docstring
Changelog: Feature: More detailed description for `--update` argument.
Docs: https://github.com/conan-io/docs/pull/1778

This flag appears in many commands: `test`, `create`, `install`, `info`, `workspace`, `graph lock`

close https://github.com/conan-io/conan/issues/7146

Problem statement:
Improve docs for '--update'  argument in commands
I got the following problem:
In my project, I normally build my packages with `conan create`.
Now I wanted to use `conan graph lock` to pickup up a previous build from Artifactory.

Now there is a different behavior between both commands.
I use semver versioning and also the `include_prerelease` option. 
Unluckily I still got a library, which require a library without `include_prerelease`.

So I got:

**ProjA** require **LibB** & **LibC**
**LibB** require **LibC**.

**ProjA** has the following requirement for **LibC**: `>=1.6.5-dev <2.0.0-dev, include_prerelease=True`
**LibB** this one for **LibC**: `^1.3.0-dev`

**LibC** exits on the Artifactory in two versions:
 * `LibC/1.6.6+master.g34a1cfb@demo/testing` -> stable version
 * `LibC/1.6.7-dev.0+master.g1fea313@demo/testing` -> prerelease version

With  `conan create` is uses:
  * `LibC/1.6.7-dev.0+master.g1fea313@demo/testing` -> prerelease version 

and with `conan graph lock`:
  * `LibC/1.6.6+master.g34a1cfb@demo/testing` -> stable version

It's the question, what is the correct result. 
Anyway it should be for both commands the same. 


### Environment Details (include every applicable attribute)
  * Operating System+version: Ubuntu LTS 18.04 and Win10
  * Compiler+version: GCC8
  * Conan version: 1.25.2
  * Python version: 3.6.9 and 3.7.5

### Steps to reproduce (Include if Applicable)

Hints from issue discussion:
Having a look at this issue, I've created a repo here (https://github.com/jgsogo/issue-7146) to reproduce the scenario with a minimal recipes.

First of all, as it is described, I get an error:

```bash
⇒  conan create projA.py
...
ERROR: Version range '^1.3.0-dev' required by 'LibB/1.0@demo/testing' not valid for downstream requirement 'LibC/1.6.7-dev.0+master.g1fea313@demo/testing'
```


```bash
⇒  conan graph lock projA.py
...
ERROR: Version range '^1.3.0-dev' required by 'LibB/1.0@demo/testing' not valid for downstream requirement 'LibC/1.6.7-dev.0+master.g1fea313@demo/testing'
```

--- 

I've modified `LibB` to include prereleases:

```
requires = "LibC/[^1.3.0-dev, include_prerelease=True]@demo/testing"
```

then:

```bash
⇒  conan create projA.py
...
WARN: LibB/1.0@demo/testing: requirement LibC/[^1.3.0-dev, include_prerelease=True]@demo/testing overridden by ProjA/1.0 to LibC/1.6.7-dev.0+master.g1fea313@demo/testing 
...
Version ranges solved
    Version range '>=1.6.5-dev <2.0.0-dev, include_prerelease=True' required by 'ProjA/1.0' resolved to 'LibC/1.6.7-dev.0+master.g1fea313@demo/testing' in local cache
    Version range '^1.3.0-dev, include_prerelease=True' required by 'LibB/1.0@demo/testing' valid for downstream requirement 'LibC/1.6.7-dev.0+master.g1fea313@demo/testing'

Installing package: ProjA/1.0
Requirements
    LibB/1.0@demo/testing from local cache - Cache
    LibC/1.6.7-dev.0+master.g1fea313@demo/testing from local cache - Cache
    ProjA/1.0 from local cache - Cache
Packages
    LibB/1.0@demo/testing:f065f71c9f26013ecf404d3b8a378899272d5edf - Missing
    LibC/1.6.7-dev.0+master.g1fea313@demo/testing:5ab84d6acfe1f23c4fae0ab88f26e3a396351ac9 - Cache
    ProjA/1.0:48b788393343665082ca528370945905800b2c44 - Build
```

and 

```bash
⇒  conan graph lock projA.py
{'1.6.6+master.g34a1cfb': LibC/1.6.6+master.g34a1cfb@demo/testing, '1.6.7-dev.0+master.g1fea313': LibC/1.6.7-dev.0+master.g1fea313@demo/testing}
1.6.7-dev.0+master.g1fea313
WARN: LibB/1.0@demo/testing: requirement LibC/[^1.3.0-dev, include_prerelease=True]@demo/testing overridden by ProjA/1.0 to LibC/1.6.7-dev.0+master.g1fea313@demo/testing 
Version ranges solved
    Version range '>=1.6.5-dev <2.0.0-dev, include_prerelease=True' required by 'projA.py (ProjA/1.0)' resolved to 'LibC/1.6.7-dev.0+master.g1fea313@demo/testing' in local cache
    Version range '^1.3.0-dev, include_prerelease=True' required by 'LibB/1.0@demo/testing' valid for downstream requirement 'LibC/1.6.7-dev.0+master.g1fea313@demo/testing'

Requirements
    LibB/1.0@demo/testing from local cache - Cache
    LibC/1.6.7-dev.0+master.g1fea313@demo/testing from local cache - Cache
Packages
    LibB/1.0@demo/testing:f065f71c9f26013ecf404d3b8a378899272d5edf - Missing
    LibC/1.6.7-dev.0+master.g1fea313@demo/testing:5ab84d6acfe1f23c4fae0ab88f26e3a396351ac9 - Cache
```

--- 

I'm getting the same version using any of the commands. Can you try recipes from the repo? Do you get the same output? Is there any difference that should be taken into account to reproduce your scenario?

About resolution order, Conan should always build the graph in the same order, but when there is a diamond Conan resolves the branch that is computed first and then checks that the requirements satisfy restrictions coming from the different branches (if not, raises an error)
Ok, sorry for the hassle. But it was again the update (this time at `conan graph lock` , see #6294) where I stumbled.
After removing the conan cache everything works fine. 
May be the documentation of the misleading "update" should be optimized?
I agree `--update` is confusing. Let's improve the docs and keep the other issue for Conan v2.0 if a new behavior is needed.

Do you have any suggestion for the help string?

Thanks!
"Check updates exist for the current `path_or_reference` from upstream remotes. 
It's not checking for updates its dependencies! Clean your local cache instead, when you want to update also the dependencies."

Commit message: update --update docstring

Patch to review:
diff --git a/conans/client/command.py b/conans/client/command.py
index c055e641936..0d60de6de8e 100644
--- a/conans/client/command.py
+++ b/conans/client/command.py
@@ -2080,7 +2080,9 @@ def _add_common_install_arguments(parser, build_help, lockfile=True):
     parser.add_argument("-r", "--remote", action=OnceArgument,
                         help='Look in the specified remote server')
     parser.add_argument("-u", "--update", action='store_true', default=False,
-                        help="Check updates exist from upstream remotes")
+                        help="Check updates exist for the current reference from upstream remotes."
+                             " It doesn't check for updates for the dependencies, clean the local"
+                             " cache to update also dependencies.")
     if lockfile:
         parser.add_argument("-l", "--lockfile", action=OnceArgument, nargs='?', const=".",
                             help="Path to a lockfile or folder containing 'conan.lock' file. "


Code review comments:
diff_hunk: @@ -2080,7 +2080,9 @@ def _add_common_install_arguments(parser, build_help, lockfile=True):
     parser.add_argument("-r", "--remote", action=OnceArgument,
                         help='Look in the specified remote server')
     parser.add_argument("-u", "--update", action='store_true', default=False,
-                        help="Check updates exist from upstream remotes")
+                        help="Check updates exist for the current reference from upstream remotes."
+                             " It doesn't check for updates for the dependencies, clean the local"
path: conans/client/command.py
text: @user1:
but --update checks for updates in dependencies too.

@author:
Ok. We need to improve this message, noone knows how it works, there are lots of issues around this flag. Let's write it.

It appears on many commands:  `test`, `create`, `install`, `info`, `workspace`, `graph lock`. Always the same behavior? What is that behavior?