Interlisp.medley/installers/cygwin/editpath/EditPath.md

EditPath

EditPath is a Windows console (text-based, command-line) program for managing the system Path and user Path.

Author

Bill Stewart - bstewart at iname dot com

License

EditPath.exe is covered by the GNU Lesser Public License (LPGL). See the file LICENSE for details.

Download

https://github.com/Bill-Stewart/PathMgr/releases/

Background

The system Path is found in the following location in the Windows registry:

Root: HKEY_LOCAL_MACHINE
Subkey: SYSTEM\CurrentControlSet\Control\Session Manager\Environment
Value name: Path

The current user Path is found in the following location in the registry:

Root: HKEY_CURRENT_USER
Subkey: Environment
Value name: Path

In both cases, the Path value is (or should be) the registry type REG_EXPAND_SZ, which means that it is a string that can contain values surrounded by % characters that Windows will automatically expand to environment variable values. (For example, %SystemRoot% will be expanded to C:\Windows on most systems.)

The Path value contains a ;-delimited list of directory names that the system should search for executables, library files, scripts, etc. Windows appends the content of the current user Path to the system Path and expands the environment variable references. The resulting string is set as the Path environment variable for processes.

EditPath provides a command-line interface for managing the Path value in the system location (in HKEY_LOCAL_MACHINE) and the current user location (in HKEY_CURRENT_USER).

Usage

The following describes the command-line usage for the program. Parameters are case-sensitive.

EditPath [options] type action

You must specify only one of the following type parameters:

type	Abbreviation	Description
--system	-s	Specifies the system Path
--user	-u	Specifies the user Path

You must specify only one of the following action parameters:

action	Abbreviation	Description
--list	-l	Lists directories in Path
--test "dirname"	-t "dirname"	Tests if directory exists in Path
--add "dirname"	-a "dirname"	Adds directory to Path
--remove "dirname"	-r "dirname"	Removes directory from Path

The following parameters are optional:

options	Abbreviation	Description
--quiet	-q	Suppresses result messages
--expand	-x	Expands environment variables (--list only)
--beginning	-b	Adds to beginning of Path (--add only)

Exit Codes

The following table lists typical exit codes when not using --test (-t).

Exit Code	Description
0	No errors
2	The Path value is not present in the registry
3	The specified directory does not exist in the Path
5	Access is denied
87	Incorrect parameter(s)
183	The specified directory already exists in the Path

The following table lists typical exit codes when using --test (-t).

Exit Code	Description
1	The specified directory exists in the unexpanded Path
2	The specified directory exists in the expanded Path
3	The specified directory does not exist in the Path

Remarks

• Anything on the command line after --test, --add, or --remove is considered to be the argument for the parameter. To avoid ambiguity, specify the action parameter last on the command line.

• Uexpanded vs. expanded refers to whether the environment variable references (i.e., names between % characters) are expanded after retrieving the Path value from the registry. For example, %SystemRoot% is unexpanded but C:\Windows is expanded.

• The --add (-a) parameter checks whether the specified directory exists in both the unexpanded and expanded copies of the Path before adding the directory. For example, if the environment variable TESTAPP is set to C:\TestApp and %TESTAPP% is in the Path, specifying --add C:\TestApp will return exit code 183 (i.e., the directory already exists in the Path) because %TESTAPP% expands to C:\TestApp.

• The --remove (-r) parameter does not expand environment variable references. For example, if the environment variable TESTAPP is set to C:\TestApp and %TESTAPP% is in the Path, specifying --remove "C:\TestApp" will return exit code 3 (i.e., the directory does not exist in the Path) because --remove does not expand %TESTAPP% to C:\TestApp. For the command to succeed, you would have to specify --remove "%TESTAPP%" instead.

• The program will exit with error code 87 if a parameter (or an argument to a parameter) is missing or not valid, if mutually exclusive parameters are specified, etc.

• The program will exit with error code 5 if the current user does not have permission to update the Path value in the registry (for example, if you try to update the system Path using a standard user account or an unelevated administrator account).

Examples

1. EditPath --expand --system --list

   This command outputs the directories in the system Path, with environment variables expanded. You can also write this command as EditPath -x -s -l.

2. EditPath --user --add "%LOCALAPPDATA%\Programs\MyApp"

   Adds the specified directory name to the user Path.

3. EditPath -s -r "C:\Program Files\MyApp\bin"

   Removes the specified directory from the system Path.

4. EditPath -s --test "C:\Program Files (x86)\MyApp\bin"

   Returns an exit code of 3 if the specified directory is not in the system Path, 1 if the specified directory is in the unexpanded copy of the system Path, or 2 if the specified directory is in the expanded copy of the system Path.