shithub: git9

ref: e2232a8ce3e56bd8bc0d6a83d82c28e49beacfec
dir: /git.1/

View raw version
.TH GIT 1
.SH NAME
git, git/conf, git/fs, git/query, git/walk, git/clone, git/branch,
git/commit, git/diff, git/init, git/log, git/merge, git/push, git/pull
\- Manage git repositories.

.SH SYNOPSIS
.PP
.B git/add
[
.B -r
]
.I path...
.PP
.B git/branch
[
.B -b
.I base
]
.I newbranch
.PP
.B git/clone
[
.I remote
[
.I local
]
]
.PP
.B git/commit
.PP
.B git/conf
[
.B -r
]
[
.B -f
.I file
]
.I keys...
.PP
.B git/diff
[
.B -b
.I branch
]
[
.I file...
]
.PP
.B git/fs
[
.B -d
]
.PP
.B git/init
[
.B -b
]
[
.I dir
]
[
.B -u
.I upstream
]
.PP
.B git/log
[
.B -b
.I branch
]
[
.I files...
]
.PP
.B git/merge
.I theirs
.PP
.B git/pull
[
.B -f
]
[
.B -u
.I upstream
]
.PP
.B git/push
[
.B -a
]
[
.B -u
.I upstream
]
[
.B -b
.I branch
]
[
.B -r
.I branch
]
.PP
.B git/query
[
.B -p
]
.PP
.B git/walk
[
.B -qc
]
[
.B -b
.I branch
]
[
.B -f
.I filters
]

.SH DESCRIPTION
.PP
Git is a distributed version control system.
This means that each repository contains a full copy of the history.
This history is then synced between computers as needed.

.PP
These programs provide tools to manage and interoperate with
repositories hosted in git.

.SH CONCEPTS

Git stores snapshots of the working directory.
Files can either be in a tracked or untracked state.
Each commit takes the current version of all tracked files and
adds them to a new commit.

This history is stored in the
.I .git
directory.
This suite of
.I git
tools provides a file interface to the
.I .git
directory mounted on
.I /mnt/git.
Modifications to the repository are done directly to the
.I .git
directory, and are reflected in the file system interface.
This allows for easy scripting, without excessive complexity
in the file API.

.SH COMMANDS

.PP
.B Git/init
is used to create a new git repository, with no code or commits.
The repository is created in the current directory by default.
Passing a directory name will cause the repository to be created
there instead.
Passing the
.B -b
option will cause the repository to be initialized as a bare repository.
Passing the
.B -u
.I upstream
option will cause the upstream to be configured to
.I upstream.

.PP
.B Git/clone
will take an existing repository, served over either the
.I git://
or
.I ssh://
protocols.
The first argument is the repository to clone.
The second argument, optionally, specifies the location to clone into.
If not specified, the repository will be cloned into the last path component
of the clone source, with the
.I .git
stripped off if present.

.B Git/push
is used to push the current changes to a remote repository.
When no arguments are provided, the remote repository is taken from
the origin configured in
.I .git/config,
and only the changes on the current branch are pushed.
When passed the
.I -a
option, all branches are pushed.
When passed the
.I -u upstream
option, the changed are pushed to
.I upstream
instead of the configured origin.
When given the
.I -r
option, the branch is deleted from origin, instead of updated.

.B Git/pull
behaves in a similar manner to git/push, however it gets changes from
the upstream repository.
After fetching, it checks out the changes into the working directory.
When passed the
.I -f
option, the update of the working copy is suppressed.
When passed the
.I -u upstream
option, the changes are pulled from
.I upstream
instead of the configured origin.

.B Git/fs
provides a read-only file system mounted on /mnt/git.
It provides a  view into the repository contents to allow convenient inspection of repository structure.
Surrounding scripts and binaries manipulate the repository contents directly.
These changes will be immediately mirrored in the file system.

.PP
Git/fs serves the following directories:

.TP
/mnt/git/object
The objects in the repo.
.TP
/mnt/git/branch
The branches and tags in the repo.
.TP
/mnt/git/ctl
A file showing the status of the repo.
Currently, it only shows the current branch.
.TP
/mnt/git/HEAD
An alias for the currently checked out commit directory.

.PP
.B Git/add
adds a file to the list of tracked files. When passed the
.I -r
flag, the file is removed from the list of tracked files.
The copy of the file in the repository is left untouched.

.PP
.B Git/commit
creates a new commit reflecting the state of the current repository.
It takes no arguments: all files must be added or removed using git/add.
If a file does not exist in the working directory, it is treated as though it was removed.

.PP
.B Git/branch
is used to switch between branches.
When passed the
.I -c
option, the branch will be created if it does not yet exist.
When passed the
.I -o original
option, the branch created is based off of
.I original
instead of
.I HEAD.
When passed the
.I -s
option, the branch is created but the files are not checked out.

.PP
.B Git/log
shows a history of the current branch.

.PP
.B Git/diff
shows the differences between the currently checked out code and
the
.I HEAD
commit.
When passed the
.I -b base
option, the diff is computed against
.I base
instead of
.I HEAD.

.PP
.B Git/merge
takes two branches and merges them filewise using
.I ape/diff3.
The next commit made will be a merge commmit.

.PP
.B Git/conf
is a tool for querying the git configuration.
The configuration key is provided as a dotted string. Spaces
are accepted. For example, to find the URL of the origin
repository, one might pass
.I 'remote "origin".url".
When given the
.I -r
option, the root of the current repository is printed.

.B Git/query
takes an expression describing a commit, or set of commits,
and resolves it to a list of commits. With the
.I -p
option, instead of printing the commit hashes, the full
path to their
.B git/fs
path is printed.

.PP
.B Git/walk
provides a tool for walking the list of tracked objects and printing their status.
With no arguments, it prints a list of paths prefixed with the status character.
When given the
.I -c
character, only the paths are printed.
When given the
.I -q
option, all output is suppressed, and only the status is printed.
When given the
.I -f
option, the output is filtered by status code, and only matching items are printed.

.PP
The status characters are as follows:
.TP
T
Tracked, not modified since last commit.
.TP
M
Modified since last commit.
.TP
R
Removed from either working directory tracking list.
.TP
A
Added, does not yet exist in a commit.

.SH REF SYNTAX

.PP
Refs are specified with a simple query syntax.
A bare hash always evaluates to itself.
Ref names are resolved to their hashes.
The
.B a ^
suffix operator finds the parent of a commit.
The
.B a b @
suffix operator finds the common ancestor of the previous two commits.
The
.B a .. b
or
.B a : b
operator finds all commits between
.B a
and
.B b.
Between is defined as the set of all commits which are ancestors of
.B b
and descendants of
.B a.

.SH EXAMPLES

.PP
In order to create a new repository, run
.B git/init:

.EX
git/init myrepo
.EE

To clone an existing repository from a git server, run:
.EX
git/clone git://github.com/Harvey-OS/harvey
cd harvey
# edit files
git/commit
git/push
.EE

.SH SOURCE
.B /sys/src/cmd/git

.SH SEE ALSO
.IR hg(1)
.IR replica(1)
.IR patch(1)
.IR diff3

.SH BUGS
.PP
Repositories with submodules are effectively read-only.

.PP
There are a number of missing commands, features, and tools. Notable
missing features include
.I http
clones, history editing, and formatted patch management.