.. default-domain:: bash

======================
J.U.S.T. Git Functions
======================

.. file:: just_git_functions.bsh

git plugin for just

.. function:: submodule-helper-list

"git submodule--helper list" bash port

Reproduces what ``git submodule--helper list`` does. Not all versions of git are modern enough to have this feature. Currently, the first three columns of information and --prefix are not reproduced because they are not needed.

:Arguments: [``$1...``] - Glob expressions to be matched, just like '`git-submodule--helper`'

:Output: ``submodule_names`` - array of submodule names (matched if filters supplied)
         ``submodule_paths`` - corresponding array of submodule paths

.. rubric:: Bugs

Unlike ``git submodule--helper list``, must be run from the toplevel (root) directory of the repository. Also, ``$1`` technically needs to match submodule.<name>.path; ``git submodule--helper`` is more forgiving.

.. function:: _is_tip_reachable

Is a commit reachable from a ref

:Arguments: ``$1`` - Submodule path (relative)
            ``$2`` - Submodule commit

:Return Value: * ``0`` - Commit is reachable from a ref
               * ``1`` - Commit is not reachable from a ref
               * ``128`` - Commit does not exist in repository

.. seealso::

  https://github.com/git/git/blob/v2.8.0/git-submodule.sh#L409 (stable through at least v2.29.0)

.. function:: _checkout_git_submodule

Helper function for :func:`safe_git_submodule_update`

:Arguments: ``$1`` - Submodule name
            ``$2`` - Submodule path (relative)
            ``$3`` - Message to print out if submodule update failed

:Output: ``presskey`` - set variable presskey on failure

.. function:: safe_git_submodule_update

Update git submodules in a smart way

git submodules are already confusing enough to work with. When a project
gets big and complicated, and add to that the potential of losing changes
that have already been committed, the default behavior of submodules is
enough to have anyone committed!

A git submodule update should update a submodule *if and only if* it is a
**ff-only merge**, and the submodule is clean (enough). Also, non-conflicting
unstaged changes are also ok too.

.. rubric:: Bugs

If the committer of the main repository changes submodules in a non-fast
forward way, this would confuse :func:`safe_git_submodule_update` because that isn't
very smart.
Update: It will at least tell you which repositories are behind now.

:Arguments: [``$1...``] - Specify submodule paths to update. None defaults to all

:Parameters: ``JUST_GIT_UPSTREAM`` - Fetch changes in the submodule using this remote. Default: ``just_upstream``
             ``$show_summary_message`` - For internal use. Disables error summary messages

.. function:: git_reattach_heads

Reattach detached heads in submodules.

:Arguments: - [``1...``] - A list of submodule paths; otherwise, all submodules will attempt to be re-attached (recursively). For example, docker/recipes

Search recursively in the current working directory for all submodules with detached heads. For each, look through all named branches (in the form of refs/heads/branch_name) for one with a SHA that matches that of the detached head (if more than one, the first one is used). If no match found, i.e., empty string, then branch is left detached.

.. function:: git_defaultify

Git plugin for just

.. command:: git_submodule-update

:Parameters: - ``JUST_GIT_UPSTREAM`` - The submodule remote name used. When :cmd:`git_submodule-update` syncs, it will use this remote. Default: ``just_upstream``
             - ``JUST_GIT_USE_REMOTE`` - The submodule remote name used for fetching the new commits. Useful if you have your own set of remotes you want to use. Default: ``${JUST_GIT_UPSTREAM}``

Recursively updates all submodules in a ff-only manner. Also reattaches heads if possible.

Sets ``JUST_GIT_SUBMODULE_SYNCED`` to ``1`` on the first run so that subsequent calls are skipped. If you have reason to call it multiple times, you can reset ``JUST_GIT_SUBMODULE_SYNCED``.

.. command:: git_make-submodules-relative

Recursively update all submodules to have relative paths.

Reset the paths in git submodules to be relative paths (relative to the $(pwd)) rather than absolute paths. This path is specified in the .git file stored in the submodule's root directory (which is how submodules are managed by git). Relative paths are now the default in git; however, there have been versions where either by design or bug, this path was absolute. The relative path of the submodule is computed using one of: a version of realpath that supports the --relative-to flag, python or perl. If none of these programs are available, the update fails.

:Uses: realpath with the --relative-to flag, python or perl.