PIP_CONFIG_FILE is used instead of per-user configuration file

Description

I've been playing with pip and its configuration files. From what I've read in documentation:
https://pip.pypa.io/en/stable/topics/configuration/#loading-order

1. when multiple configuration files are found, pip combines them;
2. and the PIP_CONFIG_FILE file is the 1st loaded file.

Now, if i define all 4 configuration files, I expect pip to load them all in the specified order.
However, when I set PIP_CONFIG_FILE, I see that it undermines (overrides, excludes) user configuration.

It is the expected behavior? Because I've got completely opposite impression from the documentation.

Expected behavior

My understanding is that the PIP_CONFIG_FILE is a separate file and should be loaded with other configuration files.

pip version

21.3.1

Python version

3.10

OS

macOS 12.0.1

How to Reproduce

# Show all config files and their values.
# $PIP_CONFIG_FILE is not defined
pip config debug
# For variant 'global', will try loading '/Library/Application Support/pip/pip.conf'
# For variant 'user', will try loading '$HOME/.pip/pip.conf'
# For variant 'user', will try loading '$HOME/.config/pip/pip.conf'
# For variant 'site', will try loading '/Library/Frameworks/Python.framework/Versions/3.10/pip.conf'
# env_var:
# env:
# global:
  # /Library/Application Support/pip/pip.conf, exists: True
    # global.verbose: true
    # global.retries: 20
    # global.no-cache-dir: true
    # list.not-required: true
# site:
  # /Library/Frameworks/Python.framework/Versions/3.10/pip.conf, exists: False
# user:
  # $HOME/.pip/pip.conf, exists: False
  # $HOME/.config/pip/pip.conf, exists: True
    # global.no-cache-dir: false
    # install.no-deps: true

# Set PIP_CONFIG_FILE
export PIP_CONFIG_FILE="$HOME/Documents/pip.conf"

# Show config files.
pip config debug
# For variant 'env', will try loading '$HOME/Documents/pip.conf'
# For variant 'global', will try loading '/Library/Application Support/pip/pip.conf'
# For variant 'site', will try loading '/Library/Frameworks/Python.framework/Versions/3.10/pip.conf'
# env_var:
  # PIP_CONFIG_FILE='$HOME/Documents/pip.conf'
# env:
  # $HOME/Documents/pip.conf, exists: True
    # global.retries: 10
    # show.files: true
# global:
  # /Library/Application Support/pip/pip.conf, exists: True
    # global.verbose: true
    # global.retries: 20
    # global.no-cache-dir: true
    # list.not-required: true
# site:
  # /Library/Frameworks/Python.framework/Versions/3.10/pip.conf, exists: False

# Show user configuration.
pip config --user list
# :env:.config-file='$HOME/Documents/pip.conf'

Output

No response

Code of Conduct

• I agree to follow the PSF Code of Conduct.

The same on Windows:

# Show all config files.
# PIP_CONFIG_FILE is not set.
pip config debug
	# env_var:
	# env:
	# global:
	#   C:\ProgramData\pip\pip.ini, exists: False
	# site:
	#   %USERPROFILE%\AppData\Local\Programs\Python\Python310\pip.ini, exists: False
	# user:
	#   %USERPROFILE%\pip\pip.ini, exists: False
	#   %USERPROFILE%\AppData\Roaming\pip\pip.ini, exists: True
	#     general.verbose: true

# Set PIP_CONFIG_FILE 
$env:PIP_CONFIG_FILE = "$env:USERPROFILE\Documents\pip.ini"

# Show all config files.
pip config debug
	# env_var:
	#   PIP_CONFIG_FILE='%USERPROFILE%\\Documents\\pip.ini'
	# env:
	#   %USERPROFILE%\Documents\pip.ini, exists: True
	# global:
	#   C:\ProgramData\pip\pip.ini, exists: False
	# site:
	#   %USERPROFILE%\AppData\Local\Programs\Python\Python310\pip.ini, exists: False

# Show user settings.
pip config --user list
	# :env:.config-file='%USERPROFILE%\\Documents\\pip.ini'

[KUGA2]

I have just witnessed the same issue on Linux (ubuntu 20.04) with pip 21.3.1 and 20.0.2

[janEbert]

According to #11249 (comment), this is intended behavior and the documentation is wrong.