stgit

stgit is a Stata program that retrieves information about a Git repository. The latest version is available through SSC: type ssc install stgit in Stata to install.

Contributing

See the contributing guide for advice on collaborating.

Stata help file

Converted automatically from SMCL:

log html stgit.sthlp stgit.md

The help file looks best when viewed in Stata as SMCL.

Title

    stgit -- Retrieve information about a Git repository


Syntax

        stgit [status], [options]

    options                     Description
    -------------------------------------------------------------------------
      git_dir(directory_name)   GIT_DIR, the directory containing the
                                  repository metadata
    -------------------------------------------------------------------------


Description

    stgit retrieves information about a Git repository, including the current
    branch and the SHA-1 hash of the current commit.  In Stata 13 and above,
    it uses the Java library JGit to return the status of the working tree.


Remarks

    In Stata 13 and above, stgit requires the SSC package statajava.  You
    must also download the JGit .jar file. (On the download page, it may be
    called the "raw API library.") Place the .jar file on your ado-path.  For
    instance, you may save it in your PERSONAL system directory.  On your
    computer, this is C:\ado\personal/.

    stgit respects version control when deciding which values to retrieve.
    Even in Stata 13 and above, if the command interpreter is set to before
    version 13, stgit does not use JGit, and returns limited information.

    One use of stgit is adding commit hashes to dataset notes and to exported
    results such as tables. This facilitates reproducible research,
    pinpointing the code that produced the files.

    The GitHub repository for stgit is here.


Options

    git_dir() specifies the path of GIT_DIR, the repository metadata
        directory. This is typically named .git.  If git_dir() is not
        specified, stgit attempts to find GIT_DIR; it assumes that the
        current working directory is within the Git repository.  Whether or
        not git_dir() is specified, stgit stores the absolute path of GIT_DIR
        in r(git_dir).


Examples

    Retrieve information about the repository within which the current
    working directory is located
        stgit

    Same as the previous stgit command
        stgit status

    Retrieve information about the repository whose GIT_DIR is
    GitHub/cfout/.git
        stgit, git_dir("GitHub/cfout/.git")


Stored results

    In Stata 9 and above, stgit stores the following in r():

    Scalars
      r(has_detached_head)   1 if HEAD is detached, 0 if not

    Macros
      r(git_dir)             absolute path of GIT_DIR
      r(sha)                 SHA-1 hash of current commit
      r(branch)              name of current branch or r(sha) if HEAD is
                               detached

    In Stata 13 and above, stgit also stores the following in r().  stgit
    retrieves these values using the JGit class org.eclipse.jgit.api.Status,
    and much of the language below is copied from that class's API (version
    3.5.3).

    Scalars
      r(is_clean)                  1 if no differences exist between the
                                     working tree, the index, and the current
                                     HEAD, 0 if differences do exist
      r(has_uncommitted_changes)   1 if any tracked file is changed, 0 if not

    Macros
      r(untracked)              list of files that are not ignored and not in
                                  the index (e.g., what you get if you create
                                  a new file without adding it to the index)
      r(untracked_folders)      list of directories that are not ignored and
                                  not in the index
      r(uncommitted_changes)    list of files and folders that are known to
                                  the repository and changed either in the
                                  index or in the working tree
      r(added)                  list of files added to the index, not in HEAD
                                  (e.g., what you get if you call git add ...
                                  on a newly created file)
      r(modified)               list of files modified on disk relative to
                                  the index (e.g., what you get if you modify
                                  an existing file without adding it to the
                                  index)
      r(changed)                list of files changed from HEAD to index
                                  (e.g., what you get if you modify an
                                  existing file and call git add ... on it)
      r(missing)                list of files in index but not filesystem
                                  (e.g., what you get if you call rm ... on
                                  an existing file)
      r(removed)                list of files removed from index, but in HEAD
                                  (e.g., what you get if you call git rm ...
                                  on an existing file)
      r(conflicting)            list of files that are in conflict (e.g.,
                                  what you get if you modify a file that was
                                  modified by someone else in the meantime)
      r(ignored_not_in_index)   list of files and folders that are ignored
                                  and not in the index


Author

    Matthew White

    For questions or suggestions, submit a GitHub issue or e-mail
    researchsupport@poverty-action.org.


Also see

    User-written:  git