\input texinfo
@c -*-texinfo-*-

@c %**start of header
@setfilename guile-git.info
@documentencoding UTF-8
@include version.texi
@settitle guile-git @value{VERSION}
@c %**end of header


@copying
This manual is for guile-git, version @value{VERSION}.

Copyright @copyright{} 2017 Erik Edrosa
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
@end copying

@dircategory The Algorithmic Language Scheme
@direntry
* Guile-Git: (guile-git). Git library for Guile.
@end direntry

@titlepage
@title guile-git Reference Manual

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents


@ifnottex
@node Top
@top guile-git

This manual is for guile-git, version @value{VERSION}.
@end ifnottex

@menu
* Introduction::     About guile-git.
* Installation::     Installing guile-git.

Tutorial sections
* Concepts::         Basic concepts for understanding git.
* Examples::         Simple examples for using guile-git.

Reference sections
* Bindings::         libgit2 setup.
* Repository::       Creating and accessing git repositories.
* Objects::          Git blobs, trees, commits, and tags.
* References::       Git references.
* Procedure Index::
@end menu

@node Introduction
@chapter Introduction

Guile-git is a GNU Guile library providing bindings to libgit2.

@node Installation
@chapter Installation

@menu
* Requirements::      Software needed to build and run guile-git.
* Building::
@end menu

@node Requirements
@section Requirements

Guile-Git depends on the following packages:

@itemize
@item
@url{https://www.gnu.org/software/guile/, GNU Guile} 2.x or 3.0
@item
@url{https://libgit2.org/, libgit2} version 1.3.x or later.
@item
@url{https://github.com/TaylanUB/scheme-bytestructures, scheme-bytestructures}
@end itemize

@node Building
@section Building

@node Concepts
@chapter Concepts

@node Examples
@chapter Examples

@node Bindings
@chapter Bindings

The module @code{git bindings} provide several definitions for
interacting with libgit2.  The main procedure is @code{libgit2-init!}
which must be called before any other guile-git procedure is called.

@deffn {Scheme Procedure} libgit2-init!
Return the number of initializations of libgit2 or an error code.

Initializes the global state of libgit2.  The procedure must be called
before any other procedure is called and may be called multiple times. 
@end deffn

@deffn {Scheme Procedure} libgit2-shutdown!
Return the number of remaining initializations of libgit2 or an error
code.

The procedure cleans up the global state of libgit2 created by
@code{libgit2-init!}.
@end deffn

@node Repository
@chapter Repository

@menu
* Repository: git-repository.   Creating and opening repositories.
* Clone: git clone.             Cloning git repositories.
* Status: git-status.           Git status.
* Checkout: git-checkout.       Git checkout.
@end menu

@node git-repository
@section Repository

The @code{(git repository)} module provides procedures for creating,
opening, and interacting with git repositories.

@deffn {Scheme Procedure} repository-init directory [is-bare]
Return a repository created at @var{directory} or throws an error if
there was an issue creating the repository.  When @var{is-bare} is
true, it creates a bare repository at @var{directory}.  When
@var{is-bare} is false, a .git directory is created at @var{directory}.
@end deffn

@deffn {Scheme Procedure} repository-open directory
Return a repository found at @var{directory} or throws an error if no
repository is found.  @var{directory} must be a git repository folder
or a working directory with a .git directory.  The procedure will open
both normal and bare repositories.
@end deffn

@deffn {Scheme Procedure} repository-open-ext directory flags [ceiling-path]
Return a repository by searching @var{directory} or parent directories
depending on @var{flags}.  @var{flags} is a list of symbols which
control the behavior of the procedure and include the following
symbols.
@table @code
@item no-search
Do not search parent directories.

@item cross-fs
Search across filesystem boundaries.

@item bare
Open repository as a bare repo.

@item no-.git
Do not check by appending .git to directory.

@item from-env
Use git environment variables.
@end table
@var{ceiling-path} is an optional list of directories where the search
for the repository should terminate.
@end deffn

@deffn {Scheme Procedure} repository-discover start-directory [across-fs] [ceiling-path]

@end deffn

@deffn {Scheme Procedure} repository-bare? repository
Return @code{#t} if @var{repository} is a bare repository and
@code{#f} otherwise.  A bare repository is a repository which does not
have a working directory.  Typically created with a guile-git
procedure like @code{(repository-init "example.git" #t)} or using
@code{--bare} on any of the repository creation commands in git.
@end deffn

@deffn {Scheme Procedure} repository-empty? repository
Return @code{#t} if @var{repository} is an empty repository and
@code{#f} otherwise.  An empty repository is a repository that has no
references and was just initialized from a procedure like
@code{(repository-init "/tmp/example")} or using @code{git init}
command.
@end deffn

@deffn {Scheme Procedure} repository-shallow? repository
Return @code{#t} if @var{repository} is a shallow clone and
@code{#f} otherwise.  A shallow repository is a repository which has a
truncated history created from cloning a repository with a depth.
@end deffn

@deffn {Scheme Procedure} openable-repository? directory
Return @code{#t} if @var{directory} is a git repository and may be
opened by procedures like @code{repository-open}.
@end deffn

@deffn {Scheme Procedure} repository-directory repository
Return the @code{.git} directory for @var{repository}.
@end deffn

@deffn {Scheme Procedure} repository-working-directory repository
Return the working directory for @var{repository} or @code{#f} if
@var{repository} is a bare repository.
@end deffn

@deffn {Scheme Procedure} repository-config repository

@end deffn

@deffn {Scheme Procedure} repository-config-snapshot repository

@end deffn

@deffn {Scheme Procedure} repository-detach-head repository

@end deffn

@deffn {Scheme Procedure} repository-get-namespace repository

@end deffn

@deffn {Scheme Procedure} repository-head repository

@end deffn

@deffn {Scheme Procedure} repository-head-detached? repository

@end deffn

@deffn {Scheme Procedure} repository-head-unborn? repository

@end deffn

@deffn {Scheme Procedure} repository-ident repository

@end deffn

@deffn {Scheme Procedure} repository-index repository

@end deffn

@deffn {Scheme Procedure} repository-refdb repository

@end deffn

@deffn {Scheme Procedure} repository-set-ident repository name email

@end deffn

@deffn {Scheme Procedure} repository-state repository

@end deffn

@node git clone
@section Clone

@deffn {Scheme Procedure} clone url directory
Return a repository by cloning a remote git repository found at
@var{url} into @var{directory} or throws an error.
@end deffn

@node git-status
@section Status

@node git-checkout
@section Checkout

@node Objects
@chapter Objects

@menu
* OID: git-oid.                Git Object IDs.
* Object: git-object.          Git objects.
* Blob: git-blob.              Git blobs.
* Tree: git-tree.              Git trees.
* Commit: git-commit.          Git commits.
* Tag: git-tag.                Git tags.
@end menu

@node git-oid
@section OID

@node git-object
@section Object

@node git-blob
@section Blob

@node git-tree
@section Tree

@node git-commit
@section Commit

@node git-tag
@section Tag

@node References
@chapter References

@menu
* Reference: git-reference.   Git references.
* Branch: git-branch.         Git branches.
* Remote: git-remote.         Git remotes.
@end menu

@node git-reference
@section Reference

@node git-branch
@section Branch

@node git-remote
@section Remote

@node Procedure Index
@unnumbered Procedure Index

@printindex fn 

@bye