.. developers:
Developers
==========
:mod:`JGit4MATLAB` is a BSD open source project for MATLAB hosted on Github.
https://github.com/mikofski/JGit4MATLAB
:mod:`JGit4MATLAB` is composed of a single class, :class:`~JGit4MATLAB.JGit`,
and a collection of private functions called from :func:`jgit`.
The :class:`~JGit4MATLAB.JGit` class is a thin wrapper around the `JGit Git API
`_. It's sole purpose is
to port the JGit Git API Java classes and methods to MATLAB and to provide
whatever additional support needed for this task.
The :func:`jgit` function is meant to be used in the MATLAB command window. It
parses a subset of Git commands for the interface expected by the
:class:`~JGit4MATLAB.JGit` class. Ideally, no new functionality should be
introduced in the :func:`jgit` function; new functionality should be added to
the :class:`~JGit4MATLAB.JGit` class.
Developing new JGit methods
---------------------------
There are many JGit and Git features that have not been ported to JGit4MATLAB.
`JGit `_ is rapidly changing project, so there are
always new features to add or modify.
Most of the :mod:`JGit4MATLAB` methods are derived from the JGit Porcelain Git
API Commands classes, which correspond to Git commands such as ``add``,
``branch``, ``checkout``, &c. Each command (or JGit class) is a method in the
:class:`JGit` class. The methods are in separate files so the interface must be
added to the main JGit file. The :class:`JGit` class and all of its methods are
located in a class folder called ``@JGit``.
Each :class:`JGit` class method corresponding to a JGit class or git command
takes ``varargin`` and uses the builtin MATLAB inputparser class.
Any Java constants and enumerations are derived up top. If necessary
``JavaMethod`` or ``JavaObject`` is used to reveal nested classes to MATLAB.
Whenever possible JGit defaults are used and JGit exceptions are not caught. As
much as possible, the :class:`JGit` class is meant to be a very thin wrapper.
Parsing new Git commands
------------------------
As new features are added to the :class:`JGit` class, new parsing functions
should be added to the private JGit4MATLAB folder and to the
:func:`jgit` function.
The parse functions are added to :func:`jgit` in a ``switch-case`` block, that
switches cases based on the command initially parsed from the command window.
Aliases may be added as extra cases, but make sure to set the cmd to the
fullname of the command or :class:`JGit` won't recognize it. Then call the
parsing function.
Parsing functions live in a private folder so that they will always be on the
same path as :func:`jgit` and :class:`JGit`. Each function is called
``parseXx.m`` in camelCase where ``Xx`` is the command. *EG: checkout is*
``parseCheckout.m``.
The parsing functions are passed all of the arguments and options, collectively
called ``argopts``, and return ``parsed_argopts``, which is a cell array
suitable for the corresponding method in :class:`JGit`.
Each parsing function has a dictionary of Git command line options. For
example, the dictionary for ``parseCheckout.m`` is as follows::
%% options
dictionary = { ...
'force',{'-f','--force'},true; ...
'newBranch',{'-b'},true; ...
'forceNew',{'-B'},true; ...
'ours',{'--ours'},true; ...
'theirs',{'--theirs'},true; ...
'set_upstream',{'--set-upstream'},true; ...
'track',{'-t','--track'},true; ...
'no_track',{'--no-track'},true};
The size of the dictionary is N x 3 for N options. The first column is a unique
name the option will be called only within the parsing function, the 2nd column
is a cell string of Git command options, and the 3rd column is a logical to
indicate if the option is logical, *IE: true or false*. The dictionary and
``argopts`` are first filtered through :func:`parseOpts` to determine if any of
the options in the dictionary are in ``argopts``. Identified options are
returned as ``options`` and popped from ``argopts``. Next :func:`filterOpts` is
used to scan for a double-hyphen, which is often used in Git to separate paths
from references. If :func:`filterOpts` second output argument is ``paths`` then
any ``argopts`` right of the double-hyphen, if present, are returned as
``paths`` and popped from ``argopts``. Otherwise ``argopts`` contains all of
arguments minus the double-hyphen if present. A warning is given by
:func:`filterOpts` if any options (preceded by single or double dash) are still
present in ``argopts`` after passing through :func:`parseOpts`. These are
options that were not in the dictionary.
Two helper functions in :func:`jgit` take care of equalsigns and integers in
options. :func:`splitEqualSigns` removes equalsigns which are sometimes used in
long options (preceded by double dash) to pass an option-argument, *EG:*
``--name=``, but which Git doesn't care about. :func:`splitShortOptions`
takes care of clustered short options (preceded by single dash) and integer
option arguments, *EG:* ``git commit -am 'my message'`` *and*
``git tag -ln100``. If these helper functions are working you shouldn't have to
use them, but it's important to know that equalsigns are removed, separating
the option from its argument, clustered short options are separated, and
integer arguments are separated from their short options. If an interger
argument is given as an option, *IE:* ``git log -10`` then option is omitted,
there isn't an option anyway, and only the integer is returned in ``argopts``.
Since the rest of ``argopts`` are strings, it should be easy to find.
Every parsed command has an entry in :func:`jgit_help` which is prints thes
subset of git commands available, the command syntax and any other basic
relevant info. These are displayed whenever ``jgit help `` is used and
should be relatively short.
Unittests
---------
There should be unittests for as many changes as possible, using the `MATLAB
Unittest framework
`_.
Documentation
-------------
These documents were created using `Sphinx `_ with the
`MATLAB Sphinx domain
`_.