ref: fed414fbad711061ab50b5a9342d50f168274494
dir: /sys/man/1/git/
.TH GIT 1
.SH NAME
git, git/conf, git/query, git/walk, git/clone, git/branch,
git/commit, git/diff, git/init, git/log, git/merge, git/push,
git/pull, git/rm, git/serve \- manage git repositories
.SH SYNOPSIS
.B git/add
[
.B -r
]
.I path ...
.PP
.B git/branch
[
.B -armns
]
[
.B -b
.I base
]
.I newbranch
.PP
.B git/clone
[
.I remote
[
.I local
]
]
.PP
.B git/commit
[
.B -re
]
[
.B -m
.I msg
]
[
.I file ...
]
.PP
.B git/compat
.PP
.B git/conf
[
.B -r
]
[
.B -f
.I file
]
.I keys ...
.PP
.B git/diff
[
.B -c
.I branch
]
[
.B -su
]
[
.I file ...
]
.PP
.B git/export
[
.I commits ...
]
.PP
.B git/import
[
.B -n
]
[
.I commits ...
]
.PP
.B git/init
[
.B -b
]
[
.B -u
.I upstream
]
[
.I dir
]
.PP
.B git/log
[
.B -c
.I commit
.B | -e
.I expr
]
[
.B -n
.I count
]
[
.B -s
]
[
.I files ...
]
.PP
.B git/merge
.I theirs
.PP
.B git/rebase
[
.B -ari
]
.I onto
.PP
.B git/pull
[
.B -fq
]
[
.B -u
.I upstream
]
.PP
.B git/push
[
.B -af
]
[
.B -u
.I upstream
]
[
.B -b
.I branch
]
[
.B -r
.I branch
]
.PP
.B git/query
[
.B -pcr
]
.I query
.PP
.B git/revert
[
.B -c
.I commit
]
.I file ...
.PP
.B git/rm
.I path ...
.PP
.B git/serve
[
.B -w
]
[
.B -r
.I path
]
.PP
.B git/walk
[
.B -qc
]
[
.B -b
.I branch
]
[
.B -f
.I filters
]
[
.B -r
.I rel
]
[
.I file ...
]
.SH DESCRIPTION
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.
.PP
This history is stored in the
.B .git
directory.
This suite of
.I git
tools provides a file interface to the
.B .git
directory mounted on
.BR $repo/.git/fs .
Modifications to the repository are done directly to the
.B .git
directory, and are reflected in the file system interface.
This allows for easy scripting, without excessive complexity
in the file API.
.SH COMMANDS
.I 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
.I Git/clone
will take an existing repository, served over either the
.B git://
or
.B 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
.B .git
stripped off if present.
.PP
.I 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
.BR .git/config ,
and only the changes on the current branch are pushed.
When passed the
.B -a
option, all branches are pushed.
When passed the
.B -u
.I upstream
option, the changes are pushed to
.I upstream
instead of the configured origin.
When given the
.B -r
option, the branch is deleted from origin, instead of updated.
.PP
.I Git/revert
restores the named files from HEAD. When passed the
.B -c
flag, restores files from
the named commit.
.PP
.I Git/pull
behaves in a similar manner to
.IR git/push ,
however it gets changes from
the upstream repository.
After fetching, it checks out the changes into the working directory.
When passed the
.B -f
option, the update of the working copy is suppressed.
When passed the
.B -q
option, the listing of changes is silenced.
When passed the
.B -u
.I upstream
option, the changes are pulled from
.I upstream
instead of the configured origin.
.PP
.I Git/serve
serves repositories using the
.B git://
protocol over stdin.
By default, it serves them read-only.
The
.B -w
flag, it allows pushing into repositories.
The
.B -r
.I path
flag serves repositories relative to
.IR path .
.PP
.I Git/fs
serves a file system on
.BR $repo/.git/fs .
For full documentation, see
.IR gitfs (4)
.PP
.I Git/add
adds a file to the list of tracked files. When passed the
.B -r
flag, the file is removed from the list of tracked files.
The copy of the file in the repository is left untouched.
.PP
.I Git/rm
is an alias for
.I git/add
.BR -r .
.PP
.I Git/commit
creates a new commit consisting of all changes to the specified files.
By default,
.I $editor
is opened to prepare the commit message.
If
.I $editor
is undefined
.IR hold (1)
is used.
The
.B -m
flag supplies the commit message directly.
The
.B -r
flag revises the contents of the previous commit, reusing the message.
The
.B -e
flag opens an editor to finalize the commit message, regardless of
whether or not it was specified explicitly or reused.
To amend a commit message,
.B -r
can be used in conjunction with
.B -m
or
.BR -e .
.PP
.I Git/branch
is used to list or switch branches.
When invoked with no arguments, it lists the current branch.
To list all branches, pass the
.B -a
option.
To switch between branches, pass a branch name.
When passed the
.B -n
option, the branch will be created, overwriting existing branch.
When passed the
.B -b
.I base
option, the branch created is based off of
.I base
instead of
.BR HEAD .
When passed the
.B -s
option, the branch is created but the files are not checked out.
When passed the
.B -r
option, the branch is removed.
.PP
When switching branches,
.I git/branch
will refuse to clobber
modifications.
Passing the
.B -m
option will cause it to attempt to merge the changes between
the branches.
.PP
.I Git/log
shows a history of the current branch.
When passed a list of files, only commits affecting
those files are shown.
The
.B -c
.I commit
option logs starting from the provided commit, instead of
.BR HEAD .
The
.B -s
option shows a summary of the commit, instead of the full message.
The
.B -n
.I count
option stops printing messages after
.I count
messages.
The
.B -e
.I expr
option shows commits matching the query expression provided.
The expression is in the syntax of
.IR git/query .
.PP
.I Git/diff
shows the differences between the currently checked out code and
the
.B HEAD
commit.
When passed the
.B -c
.I base
option, the diff is computed against
.I base
instead of
.BR HEAD .
When passed the
.B -s
option, only the file statuses are
printed.
When passed the
.B -u
option, untracked files are listed.
The
.B -u
option
implies
.BR -s .
.PP
.I Git/export
exports a list of commits in a format that
.I git/import
can apply.
If multiple patches are generated,
they are separated with a ⑨ character.
.PP
.I Git/import
imports a commit with message, author, and
date information.
When passed the
.B -n
option,
it applies the contents of the commit without committing to the branch.
Git/import can accept multiple patches on stdin.
When multiple patches are supplied, each patch must be separated with a ⑨ character.
.PP
.I Git/merge
takes two branches and merges them filewise using
.I merge3
(see
.IR diff (1)).
The next commit made will be a merge commit.
.PP
.I Git/rebase
takes one branch and moves it onto another.
On error, the remaining commits to rebase are
saved, and can be resumed once the conflict is
resolved using the
.B -r
option.
If the rebase is to be aborted, the
.B -a
option will clean up the in progress rebase
and reset the state of the branch.
The
.B -i
option will open an editor to modify the todo-list before the rebase
begins.
.PP
The following rebase commands are supported:
.TP 10
.B pick
Apply the commit.
.TP
.B reword
Apply the commit, then edit its commit message.
.TP
.B edit
Apply the commit, then exit to allow further changes.
.TP
.B squash
Fold the commit into the previous commit, then edit the combined
commit message.
.TP
.B fixup
Fold the commit into the previous commit, discarding its commit
message.
.TP
.B break
Exit to allow for manual edits or inspection before continuing.
.PP
.I 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
.BR 'remote\ \C'"'origin\C'"'.url' .
When given the
.B -r
option, the root of the current repository is printed.
.PP
.I Git/query
takes an expression describing a commit, or set of commits,
and resolves it to a list of commits.
The
.B -r
option reverses the order of the commit list.
With the
.B -p
option, instead of printing the commit hashes, the full
path to their
.I git/fs
path is printed. With the
.B -c
option, the query must resolve to two commits.
The blobs
that have changed in the commits are printed.
.PP
.I Git/walk
shows the status of files in the repository.
It prints a list of paths prefixed with the status character.
It exits with a non-empty status if the repository is not clean.
The
.B -c
option suppresses the status, so only the paths are printed.
The
.B -q
option suppresses all output.
The
.B -r
option causes paths to be printed relative to the supplied directory
.IR rel .
The
.B -f
option filters files by status, and only matching items are printed.
By default, the filters are
.BR TRMA .
.PP
The status characters are as follows:
.TP
T
Tracked, not modified since last commit.
.TP
M
Modified since last commit.
.TP
R
This file will be gone in the next commit.
.TP
A
This file will be present in the next commit.
.TP
U
This file is not tracked by git.
.PP
.I Git/compat
spawns an rc subshell with a compatibility stub in
.BR $path .
This compatibility stub provides enough of the Unix
.I git
commands to run tools like
.I go get
but not much more.
.SH REF SYNTAX
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
.BR b .
Between is defined as the set of all commits which are reachable from
.B b
but not reachable from
.BR a .
.SH PROTOCOLS
Git supports URL schemes of the format
.IB transport :// dial / repo .
The
.I transport
portion specifies the protocol to use.
If the
.I transport
portion is omitted, then the transport used is
.BR ssh .
The
.I dial
portion is either a Plan 9 dial string, or a conventional
.IB host : port
pair.
For the
.B ssh
protocol, it may also include a
.IB user @
prefix.
.I repo
portion is the path of the repository on the server.
.PP
The supported transports are
.BR ssh:// ,
.BR git:// ,
.BR hjgit:// ,
.BR gits:// ,
.BR http:// ,
and
.BR https:// .
Two of these are specific to git9:
.B gits://
and
.BR hjgit:// .
Both are the
.B git://
protocol, tunneled over TLS.
.B Hjgit://
authenticates with the server using Plan 9 authentication,
using
.IR tlsclient\ -a .
Any of these protocol names may be prefixed with
.BR git+ ,
for copy-paste compatibility with Unix git.
.SH EXAMPLES
In order to create a new repository, run
.I git/init:
.IP
.EX
git/init myrepo
.EE
.PP
To clone an existing repository from a git server, run:
.IP
.EX
git/clone https://github.com/Harvey-OS/harvey
cd harvey
# edit files
git/commit foo.c
git/push
.EE
.PP
To set a user and email for commits, run:
.IP
.EX
% mkdir $home/lib/git
% >$home/lib/git/config echo '
[user]
name = Ori Bernstein
email = ori@eigenstate.org
\&'
.EE
.SH FILES
.TP
.B $repo/.git
The full git repository.
.TP
.B $repo/.git/config
The configuration file for a repository.
.TP
.B $home/lib/git/config
The user-wide configuration for git.
The contents of this file are used as fallbacks for the per-repository config.
.TP
.B /sys/lib/git/config
The system-wide configuration for git.
The contents of this file are used as fallbacks for the per-user config.
.SH SEE ALSO
.IR diff (1),
.IR patch (1),
.IR replica (1),
.IR gitfs (4)
.SH BUGS
Repositories with submodules are effectively read-only.
.PP
There are some missing commands, features, and tools.
.PP
.I Git/compat
only works within a git repository.
.PP
Sharing git repositories between Plan 9 and Linux leads to indexes going out of sync.
To work around this, reset the state of the tracked files on Plan 9 with
.I git/add:
.IP
.EX
git/add `{@{git/fs && git/walk -c}}
.EE
.PP
And on Linux, with:
.IP
.EX
git checkout HEAD -- $(find . -type f)
.EE