Testing different code branches

Wiki
1

There may be some circumstances in which one of the MRtrix3 developers requests / suggests using an alternative “branch” of code, in order to test a potential fix to some issue or try out some new functionality. In this situation, the relevant code changes / additions are actually accessible within the version control software git that is used to manage MRtrix3 changes; the trick is how to access them.

For users not accustomed to using git, the following is probably the safest mechanism for executing different code branches:

  1. Make a fresh clone of the MRtrix3 repository, so as not to interfere with the standard MRtrix3 installation that you use on a day-to-day basis:

    $ git clone https://github.com/MRtrix3/mrtrix3.git dirname/

    (here the copy of MRtrix3 will be created in a new directory with name “dirname”; feel free to call this directory whatever you wish, and to place it wherever you wish)

  2. Navigate into this directory:

    $ cd dirname/

  3. Check out the code branch that corresponds to the code branch that you wish to access:

    $ git checkout branchname

    (here “branchname” must correspond to the name of a git branch that is a part of the MRtrix3 repository)

  4. Configure MRtrix3

    $ ./configure

  5. Build MRtrix3

    $ ./build bin/commandname

    In this particular example, only the MRtrix3 command called “commandname” is built, rather than building all MRtrix3 binaries. This will reduce total compilation time in the instance where you only wish to test one specific (binary) command within this specific code branch, and therefore compilation of all other commands is not necessary. Note that this does not work for scripts as they can not be compiled and you’d get an error message about a missing .cpp file. Scripts might depend on a number of binaries so it is safest to build all commands by omitting bin/commandname from the ./build call.

  6. Execute the relevant command:

    $ ~/dirname/bin/commandname ...

    In a typical MRtrix3 installation, one would ensure that the location of the MRtrix3 bin/ directory is added to the PATH environment variable, so that commands can be executed simply by typing their name. Here we explicitly do not do this. Instead, the full filesystem path to the executable file must be specified. In this way, the fact that it is an alternative version of this particular command that is being executed is entirely explicit.

    Beware though: If you forget to provide the full path to the command, and simply type “commandname” in the terminal, it will be the version of this command that resides in your standard MRtrix3 installation that is executed; not this separate version.

  7. If you no longer require use of this particular code branch, simply erase directory “dirname/”.

The alternative approach to testing different code branches is to access those code branches using your existing MRtrix3 installation. The disadvantage of this approach is that if you fail to revert your installation back to the original version and recompile, then you may inadvertently continue using some version of the software other than what you intended.

  1. Navigate to your MRtrix3 installation:

    $ cd mrtrix3/

    (modify with wherever MRtrix3 is installed on your system)

  2. Check what version of MRtrix3 you are currently using:

    $ git status | head -n1

    This will tell you whether you are currently accessing some branch, or a specific tagged version.

  3. Update your local repository clone to make it aware of any new content in the online repository:

    $ git fetch

    Note: This will not influence your installation in any way.

  4. “Check out” the version of the code that you wish to access:

    $ git checkout branchname

    (replace “branchname” with the name of whatever code branch you wish to access)

  5. Recompile MRtrix3:

    $ ./build bin/commandname

    As with the previous example, here a specific MRtrix3 command of interest called “commandname” is compiled.

    Note also here that if you now attempt to run some MRtrix3 binary executable other than the command of interest that has been explicitly compiled, it should fail. This is a handy reminder that there is a mismatch between the code that you used to compile the command of interest, and what was used previously in the compilation of the other MRtrix3 commands. If you in fact want to be able to run all other MRtrix3 commands while accessing this separate code branch, simply run “./build” to re-build all executables.

  6. Test the alternative version of the command:

    $ commandname ...

  7. When you have completed testing of this alternative code, and wish to revert back to the code that you were running prior to this experiment, re-“check out” the version of the code that you were using previously:

    $ git checkout master
$ ./build

    (here it is the “master” branch that is accessed, which contains the most recent tag update along with any bug fixes thereof; this is the default branch that is accessed when you first create a local clone of the MRtrix3 repository, so will be the intended target branch for many users)