The .rosinstall file is generated when rosinstall is executed. (Except the .rosinstall files in /opt/ros/*/.rosinstall are generated by the debbuilding infrastructure.)
1) When executed rosinstall will generate a new .rosinstall which is the union of the existing .rosinstall and rosinstall files on the command line. Before writing out the .rosinstall file the entries will be deduplicated based on local-name. If you run rosinstall . it will make sure that you have exactly what's listed in the .rosinstall file, with the same version as listed. If you change the .rosinstall file manually before executing it will follow the edited version. If you have changed an svn checkout manually it will try to return the checkout to the version in the .rosinstall file, unless you change the .rosinstall file to correspond. (PS rosinstall version 0.5.15 has an interactive skip option to not change a locally changed checkout)
The recommended way to update is to call `rosinstall . "updated_rosinstall_file"
where updated_rosinstall_file would be something manually maintained or a generated file like "http://packages.ros.org/cgi-bin/gen_rosinstall.py?rosdistro=diamondback&variant=desktop-full&overlay=no" The new rules for each local-name will override the corresponding old rules.
2) Similarly to updating to add a package or stacks to an existing rosinstalled directory, just pass a rosinstall file with those packages to rosinstall rosinstall . new_packages.rosinstall and they will be added to the .rosinstall in directory "."
Adding the lines to .rosinstall is also valid. Then rerun rosinstall like this rosinstall .
To add build a rosinstall on top of another one without changing an existing checkout you will want to use another directory. Then you can use rosinstall . /other_checkout/path local.rosinstall as long as /other_checkout/path contains a .rosinstall file. This will add the contents of the /othere_checkout/path as "other" elements in the .rosinstall file in "."
As always later arguments will be earlier on the ROS_PACKAGE_PATH.
