git.pl -- Run GIT commands

This module performs common GIT tasks by calling git as a remote process through process_create/3. It requires that the git executable is in the current PATH.

This module started life in ClioPatria and has been used by the Prolog web-server to provide information on git repositories. It is now moved into the core Prolog library to support the Prolog package manager.

git(+Argv, +Options) is det

Run a GIT command. Defined options:

directory(+Dir): Execute in the given directory
output(-Out): Unify Out with a list of codes representing stdout of the command. Otherwise the output is handed to print_message/2 with level informational.
error(-Error): As output(Out), but messages are printed at level error.
askpass(+Program): Export GIT_ASKPASS=Program

git_process_output(+Argv, :OnOutput, +Options) is det

Run a git-command and process the output with OnOutput, which is called as call(OnOutput, Stream).

git_open_file(+GitRepoDir, +File, +Branch, -Stream) is det

Open the file File in the given bare GIT repository on the given branch (treeisch).

bug: - We cannot tell whether opening failed for some reason.

is_git_directory(+Directory) is semidet

True if Directory is a git directory (Either checked out or bare).

git_describe(-Version, +Options) is semidet

Describe the running version based on GIT tags and hashes. Options:

match(+Pattern): Only use tags that match Pattern (a Unix glob-pattern; e.g. V*)
directory(Dir): Provide the version-info for a directory that is part of a GIT-repository.
commit(+Commit): Describe Commit rather than HEAD

See also: - git describe

git_hash(-Hash, +Options) is det

Return the hash of the indicated object.

is_git_hash(+Atom) is semidet

True when Atom represents a GIT hash, i.e., a 40 digit hexadecimal string.

git_ls_tree(-Entries, +Options) is det

True when Entries is a list of entries in the the GIT repository, Each entry is a term:

object(Mode, Type, Hash, Size, Name)

git_remote_url(+Remote, -URL, +Options) is det

URL is the remote (fetch) URL for the given Remote.

git_ls_remote(+GitURL, -Refs, +Options) is det

Execute git ls-remote against the remote repository to fetch references from the remote. Options processed:

heads(Boolean)
tags(Boolean)
refs(List)

For example, to find the hash of the remote HEAD, one can use

?- git_ls_remote('git://www.swi-prolog.org/home/pl/git/pl-devel.git',
                 Refs, [refs(['HEAD'])]).
Refs = ['5d596c52aa969d88e7959f86327f5c7ff23695f3'-'HEAD'].

Arguments:

Refs

- is a list of pairs hash-name.

git_remote_branches(+GitURL, -Branches) is det

Exploit git_ls_remote/3 to fetch the branches from a remote repository without downloading it.

git_default_branch(-BranchName, +Options) is det

True when BranchName is the default branch of a repository. This is hard to define. If possible, we perform rev-parse on origin/HEAD. If not, we look at branches shared between the local and remote and select main or master or the first common breach. Options:

remote(+Remote): Remote used to detect the default branch. Default is origin.

git_default_branch(-BranchName, +Options) is semidet

True when BranchName is the current branch of a repository. Fails if the repo HEAD is detached

git_branches(-Branches, +Options) is det

True when Branches is the list of branches in the repository. In addition to the usual options, this processes:

contains(Commit): Return only branches that contain Commit.
remote(true): Return remote branches

git_tags(-Tags, +Options) is det

True when Tags is a list of git tags defined on the repository.

git_tags_on_branch(+Dir, +Branch, -Tags) is det

Tags is a list of tags in Branch on the GIT repository Dir, most recent tag first.

See also: - Git tricks at http://mislav.uniqpath.com/2010/07/git-tips/

git_shortlog(+Dir, -ShortLog, +Options) is det

Fetch information like the GitWeb change overview. Processed options:

limit(+Count): Maximum number of commits to show (default is 10)
revisions(+Revisions): Git revision specification
path(+Path): Only show commits that affect Path. Path is the path of a checked out file.
git_path(+Path): Similar to path, but Path is relative to the repository.

Arguments:

ShortLog - is a list of git_log records.

git_show(+Dir, +Hash, -Commit, +Options) is det

Fetch info from a GIT commit. Options processed:

diff(Diff): GIT option on how to format diffs. E.g. stat
max_lines(Count): Truncate the body at Count lines.

Arguments:

Commit - is a term git_commit(...)-Body. Body is currently a list of lines, each line represented as a list of codes.

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

git_current_branch(Arg1, Arg2)
git_commit_data(Arg1, Arg2, Arg3)
git_log_data(Arg1, Arg2, Arg3)