1. There is 2 locations for Path variable

1. What is the purpose of PATH?

PATH is an environment variable that contains a colon-separated list of directories where your shell will look for executables that you name on the command line without providing an explicit path to them (as in your jsdoc example). Thus, if your PATH has

/usr/bin:/bin:/home/bin

then any executable you call by name will be searched for in these directories (in that order) and the first executable found is the one executed.

2. What is the difference between /etc/paths and ~/.bash_profile

According to this question on ServerFault, /etc/paths is used to set PATH globally (i.e. system-wide, for all users) while ~/.bash_profile is used to set per-user preferences (where ~ will be the user's home directory). What is written in .bash_profile can either add to the global PATHfrom /etc/paths or override it completely.

For the record, /etc/paths seems to be a MAC OS peculiarity: I haven't come across it on GNU/Linux, at least.

2. How to update the Path at user level (recommended)

The recommended way is by editing your .bash_profile file. This file is read and the commands in it executed by Bash every time you log in to the system. The best part is that this file is specific to your user so you won’t affect other users on the same system by changing it.

Step 1: Open up a Terminal window (this is in your Applications/Utilites folder by default)

Step 2: Enter the follow commands:

touch ~/.bash_profile; open ~/.bash_profile

This will open the .bash_profile file in Text Edit (the default text editor included on your system). The file allows you to customize the environment your user runs in.

Step 3: Add the following line to the end of the file adding whatever additional directory you want in your path:

export PATH=" $HOME/.rbenv/bin:$ PATH"

That example would add ~/.rbenv to the PATH. The $PATH part is important as it appends the existing PATH to preserve it in the new value.

Step 4: Save the .bash_profile file and Quit (Command + Q) Text Edit.

Step 5: Force the .bash_profile to execute. This loads the values immediately without having to reboot. In your Terminal window, run the following command.

source ~/.bash_profile

That’s it! Now you know how to edit the PATH on your Mac OS X computer system. You can confirm the new path by opening a new Terminal windows and running:

echo $PATH

You should now see the values you want in your PATH.

[Updated 2/10/2012] The instructions now use the .bash_profile method of editing your PATH. This is preferred as it keeps the changes specific to your user. I also updated the instructions to use Text Edit instead of vim so it is easier for a beginner.