Document how to rename (move) project directory

[JDLH]

Is your feature request related to a problem? Please describe.

I am a developer with an existing project directory managed by pipenv. I want to move my project directory (rename the directory and/or move it to a different parent directory). This breaks the connection between the project directory and the environment directory.

The workaround is to remove the pipenv management of the project directory via pipenv --rm, then move or rename the project directory, then restore pipenv management via pipenv install. (Source: answer to discussion #5123 "How do I rename or move a directory managed by pipenv?".)

Describe the solution you'd like

A section of the documentation entitled, "How to rename or move the project directory", in either the Basics documentation (docs/basics.rst) or Advanced documentation (docs/advanced.rst). A few sentences should be enough to describe the method. The title should attract the attention of a developer wanting to rename their project directory and wondering how to do it right.

Also describe what a developer should do who has renamed their directory, discovered that things have broken, and who wants to recover.

Describe alternatives you've considered

The Install documentation section, ''Virtualenv mapping caveat'', does say,

The virtualenv is stored globally with the name of the project’s root directory plus the hash of the full path to the project’s root (e.g., my_project-a3de50).

If you change your project’s path, you break such a default mapping and pipenv will no longer be able to find and to use the project’s virtualenv.

You might want to set export PIPENV_VENV_IN_PROJECT=1 in your .bashrc/.zshrc (or any shell configuration file) for creating the virtualenv inside your project’s directory, avoiding problems with subsequent path changes.

This is clearly relevant, but also when I had the question, I could not find the answer here. Thus I think this information belongs in Basics or Advanced, with a clearly relevant heading, instead.

Additional context

Related issues:

• How do I rename or move a directory managed by pipenv? #5123 ''How do I rename or move a directory managed by pipenv?'' asks the question and gives the answer.
• [Feature] Command to move project folder, and command to scan for and remove orphaned virtualenvs #4934 ''[Feature] Command to move project folder, and command to scan for and remove orphaned virtualenvs'' proposes code to make it easier to preserve the environment when moving directories. This issue proposes improving the documentation of the current code.
• How does pipenv know the virtualenv for current project ? #796 ''How does pipenv know the virtualenv for current project?'' is at the root asking for this documentation, or for the feature.

---

I am running pipenv 2022.5.2 on macOS Monterey 12.4.

[langaa-egeskov]

Hi there! I had the same confusion and this thread and #5123 were helpful. I also looked for the answer the docs before I came to github issue page, so it does seem like it would be great to have the quick fix in the documentation. l looked at the contribution rules and only made a small change to the documentation. There were 2 spots where the behavior of virtualenv was touched on but maybe not as full explained in terms of how to handle moving a project folder. I basically tried to just place the explanation (given by @j-mo in issue #5123 ) into the documentation at these points. I made the section Virtualenv-mapping-caveat more explicit and added a heading under Virtualenv. But, I am a first-timer committer, so not sure if just editing the markdown files as I did was the change that is needed.