*! version 1.0.1 Matthew White 09mar2015

Title

stgit -- Retrieve information about a Git repository

Syntax

stgit [status], [options]

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 .

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