Pipenv: Documentation: `--ignore-pipfile` should be more clear; mention `pipenv sync`

[de-code]

The --ignore-pipfile flag reads:

Ignore Pipfile when installing, using the Pipfile.lock.

That would suggest it always installs dependencies as per the Pipfile.lock file which doesn't exactly seem to be the case.

pipenv sync was added and only in the advanced documentation it mentions:

pipenv install --ignore-pipfile is nearly equivalent to pipenv sync, but pipenv sync will never attempt to re-lock your dependencies as it is considered an atomic operation. pipenv install by default does attempt to re-lock unless using the --deploy flag.

That distinction seems to be key and shouldn't be hidden in the advanced section.

An intuitive command for installing dependencies is pipenv install which was used before. It would make sense that if the documentation for pipenv install would itself point to pipenv sync as both are installing dependencies. And it's not obvious one should maybe look for pipenv sync.

[alexpirine]

Hi, could you please clarify pipenv install, pipenv install --deploy, pipenv install --ignore-pipfile, a combination of both, and pipenv sync? Seems like a lot of variations to me…

[alexpirine]

Without forgetting that pipenv install --system seems to be appropriate for building docker images…

[anentropic]

The docs are totally unclear

It seems like the default when doing pipenv install should be to install the versions pinned in the lockfile, but if it did that then why does pipenv install --ignore-pipfile exist?

Re-reading the docs it seems that pipenv sync does what I want:

"you can install packages exactly as specified in Pipfile.lock using the sync command"
(whereas presumably pipenv install would install latest versions and update the lock)

But then what does pipenv install --ignore-pipfile do differently?

The docs say:

pipenv install --ignore-pipfile is nearly equivalent to pipenv sync, but pipenv sync will never attempt to re-lock your dependencies as it is considered an atomic operation. pipenv install by default does attempt to re-lock unless using the --deploy flag.

It is not clear what this actually means in practice. I _think_ it means that if you have installed/updated packages outside of pipenv, leaving your Pipfile.lock out of date, pipenv install --ignore-pipfile will update the lock file before installing from the lock. If it doesn't mean that then I have no idea.

[joaomcarlos]

This is extremely confusing.

What I think it should be (and already is ... _for the most part_):

• install should just install dependencies pinned on the pipfile.lock. If no pipfile.lock exists, install latest and create a pipfile.lock. In any other instance, do not touch the pipfile.lock.
• lock should be used when we are sure we want the versions currently installed. All other commands should warn us to run it, if we mess up, we have it versioned (in GIT) already anyway.
• sync in its current state, makes no sense, in my mind its the same as lock but currently thats not the case.
• install --ignore-pipfile makes no sense.
• update should get the latest version and warn us about updating pipfile.lock.
• update <specific> should update get the latest of a single package and warn us about updating pipfile.lock.
• install --dev (install both default and develop) makes no sense, should be just install.
• install --deploy should be used instead if no develop packages are wanted.

[januszm]

Totally agree with @joaomcarlos , perhaps it deserves its own GH Issue?

Also, it seems that the behaviour of pipenv install changed recently. The --help says that :

install    Installs provided packages and adds them to Pipfile, or (if no
             packages are given), installs all packages from Pipfile.

which is not true anymore because:

$ pipenv install
Installing dependencies from Pipfile.lock (abc683)…

[lapinvert]

@joaomcarlos If I correctly read the docs, install --deploy is just a regular install that throws an error if the lock file is out of sync. Therefore it still makes sense to use it as well as install --dev.

The other issues raised here are problematic tho and that would be great to see them addressed.