ref: bdf2c7a8d806e751327f7c6ab02778d2a8b2fd22
parent: 4ae7a48e2303130a6634f6eef1f6d56118bbd6d1
author: Lennart Jablonka <humm@ljabl.com>
date: Sun Feb 2 19:00:00 EST 2025
git(1): follow conventions more closely 1. plan on working on some project P 2. notice some random man page could be improved 3. improve man page 4. time’s up; you haven’t worked on P
--- a/sys/man/1/git
+++ b/sys/man/1/git
@@ -2,15 +2,13 @@
.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.
-
+git/pull, git/rm, git/serve \- manage git repositories
.SH SYNOPSIS
-.PP
.B git/add
[
.B -r
]
-.I path...
+.I path ...
.PP
.B git/branch
[
@@ -35,10 +33,11 @@
.B -re
]
[
-.B -m msg
+.B -m
+.I msg
]
[
-.I file...
+.I file ...
]
.PP
.B git/compat
@@ -51,7 +50,7 @@
.B -f
.I file
]
-.I keys...
+.I keys ...
.PP
.B git/diff
[
@@ -62,12 +61,12 @@
.B -su
]
[
-.I file...
+.I file ...
]
.PP
.B git/export
[
-.I commits...
+.I commits ...
]
.PP
.B git/import
@@ -75,7 +74,7 @@
.B -n
]
[
-.I commits...
+.I commits ...
]
.PP
.B git/init
@@ -83,12 +82,12 @@
.B -b
]
[
-.I dir
-]
-[
.B -u
.I upstream
]
+[
+.I dir
+]
.PP
.B git/log
[
@@ -105,7 +104,7 @@
.B -s
]
[
-.I files...
+.I files ...
]
.PP
.B git/merge
@@ -115,9 +114,7 @@
[
.B -ari
]
-[
-.B onto
-]
+.I onto
.PP
.B git/pull
[
@@ -156,10 +153,10 @@
.B -c
.I commit
]
-.I file...
+.I file ...
.PP
.B git/rm
-.I path...
+.I path ...
.PP
.B git/serve
[
@@ -187,45 +184,37 @@
.I rel
]
[
-.I file...
+.I file ...
]
-
.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.
-
+.PP
This history is stored in the
-.I .git
+.B .git
directory.
This suite of
.I git
tools provides a file interface to the
-.I .git
+.B .git
directory mounted on
-.IR $repo/.git/fs .
+.BR $repo/.git/fs .
Modifications to the repository are done directly to the
-.I .git
+.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
-
-.PP
-.B Git/init
+.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
@@ -238,13 +227,12 @@
.I upstream
option will cause the upstream to be configured to
.I upstream.
-
.PP
-.B Git/clone
+.I Git/clone
will take an existing repository, served over either the
-.I git://
+.B git://
or
-.I ssh://
+.B ssh://
protocols.
The first argument is the repository to clone.
The second argument, optionally, specifies the location to clone into.
@@ -252,13 +240,12 @@
of the clone source, with the
.B .git
stripped off if present.
-
.PP
-.B Git/push
+.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
-.I .git/config,
+.BR .git/config ,
and only the changes on the current branch are pushed.
When passed the
.B -a
@@ -272,17 +259,17 @@
When given the
.B -r
option, the branch is deleted from origin, instead of updated.
-
.PP
-.B Git/revert
+.I Git/revert
restores the named files from HEAD. When passed the
.B -c
flag, restores files from
the named commit.
-
.PP
-.B Git/pull
-behaves in a similar manner to git/push, however it gets changes from
+.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
@@ -297,11 +284,10 @@
option, the changes are pulled from
.I upstream
instead of the configured origin.
-
.PP
-.B Git/serve
+.I Git/serve
serves repositories using the
-.I git://
+.B git://
protocol over stdin.
By default, it serves them read-only.
The
@@ -309,31 +295,28 @@
flag, it allows pushing into repositories.
The
.B -r
-.B path
+.I path
flag serves repositories relative to
.IR path .
-
.PP
-.B Git/fs
+.I Git/fs
serves a file system on
-.IR $repo/.git/fs .
+.BR $repo/.git/fs .
For full documentation, see
.IR gitfs (4)
-
.PP
-.B Git/add
+.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
-.B Git/rm
+.I Git/rm
is an alias for
.I git/add
.BR -r .
-
.PP
-.B Git/commit
+.I Git/commit
creates a new commit consisting of all changes to the specified files.
By default,
.I $editor
@@ -359,9 +342,8 @@
.B -m
or
.BR -e .
-
.PP
-.B Git/branch
+.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
@@ -377,7 +359,7 @@
option, the branch created is based off of
.I base
instead of
-.IR HEAD .
+.BR HEAD .
When passed the
.B -s
option, the branch is created but the files are not checked out.
@@ -385,15 +367,16 @@
.B -r
option, the branch is removed.
.PP
-When switching branches, git/branch will refuse to clobber
+When switching branches,
+.I git/branch
+will refuse to clobber
modifications.
Passing the
.B -m
-option will cause git9 to attempt to merge the changes between
+option will cause it to attempt to merge the changes between
the branches.
-
.PP
-.B Git/log
+.I Git/log
shows a history of the current branch.
When passed a list of files, only commits affecting
those files are shown.
@@ -401,7 +384,7 @@
.B -c
.I commit
option logs starting from the provided commit, instead of
-.IR HEAD .
+.BR HEAD .
The
.B -s
option shows a summary of the commit, instead of the full message.
@@ -416,13 +399,12 @@
.I expr
option shows commits matching the query expression provided.
The expression is in the syntax of
-.B git/query.
-
+.IR git/query .
.PP
-.B Git/diff
+.I Git/diff
shows the differences between the currently checked out code and
the
-.I HEAD
+.B HEAD
commit.
When passed the
.B -c
@@ -430,7 +412,7 @@
option, the diff is computed against
.I base
instead of
-.I HEAD.
+.BR HEAD .
When passed the
.B -s
option, only the file statuses are
@@ -443,29 +425,28 @@
option
implies
.BR -s .
-
.PP
-.B Git/export
+.I Git/export
exports a list of commits in a format that
-.B git/import
+.I git/import
can apply.
-
.PP
-.B Git/import
+.I Git/import
imports a commit with message, author, and
-date information. When passed the
+date information.
+When passed the
.B -n
option, applies the contents of the commit without
committing to the branch.
-
.PP
-.B Git/merge
+.I Git/merge
takes two branches and merges them filewise using
-.IR ape/diff3 .
+.I merge3
+(see
+.IR diff (1)).
The next commit made will be a merge commit.
-
.PP
-.B Git/rebase
+.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
@@ -480,7 +461,6 @@
.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
@@ -503,19 +483,19 @@
.TP
.B break
Exit to allow for manual edits or inspection before continuing.
-
.PP
-.B Git/conf
+.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
+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
-.IR 'remote\ \C'"'origin\C'"'.url' .
+.BR 'remote\ \C'"'origin\C'"'.url' .
When given the
.B -r
option, the root of the current repository is printed.
-
-.B Git/query
+.PP
+.I Git/query
takes an expression describing a commit, or set of commits,
and resolves it to a list of commits.
The
@@ -525,14 +505,14 @@
.B -p
option, instead of printing the commit hashes, the full
path to their
-.B git/fs
+.I git/fs
path is printed. With the
.B -c
-option, the query must resolve to two commits. The blobs
+option, the query must resolve to two commits.
+The blobs
that have changed in the commits are printed.
-
.PP
-.B Git/walk
+.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.
@@ -551,7 +531,6 @@
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
@@ -569,20 +548,16 @@
.TP
U
This file is not tracked by git.
-
.PP
-.B Git/compat
+.I Git/compat
spawns an rc subshell with a compatibility stub in
-.IR $path .
-This compatibility stub provides enough of the unix
+.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
-
-.PP
Refs are specified with a simple query syntax.
A bare hash always evaluates to itself.
Ref names are resolved to their hashes.
@@ -599,59 +574,63 @@
operator finds all commits between
.B a
and
-.B b.
+.BR b .
Between is defined as the set of all commits which are reachable from
.B b
but not reachable from
-.B a.
-
+.BR a .
.SH PROTOCOLS
-.PP
Git supports URL schemes of the format
-.BR transport://dial/repo/path .
-The transport portion specifies the protocol to use.
-If the transport portion is omitted, then the transport used is
+.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
-.I host:port
+portion is either a Plan 9 dial string, or a conventional
+.IB host : port
pair.
-For the ssh protocol, it may also include a
-.I user@
+For the
+.B ssh
+protocol, it may also include a
+.IB user @
prefix.
-.I repo/path
+.I repo
portion is the path of the repository on the server.
-
+.PP
The supported transports are
-.B ssh://, git://, hjgit://, gits://, http://,
+.BR ssh:// ,
+.BR git:// ,
+.BR hjgit:// ,
+.BR gits:// ,
+.BR http:// ,
and
-.BR https .
+.BR https:// .
Two of these are specific to git9:
-.I gits://
+.B gits://
and
-.IR hjgit:// .
+.BR hjgit:// .
Both are the
-.I git://
-protocol, tunneled over tls.
-.I Hjgit://
+.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
-.IR git+ ,
+.BR git+ ,
for copy-paste compatibility with Unix git.
-
.SH EXAMPLES
-
-.PP
In order to create a new repository, run
-.B git/init:
+.I git/init:
.IP
.EX
git/init myrepo
.EE
-
.PP
To clone an existing repository from a git server, run:
.IP
@@ -662,7 +641,6 @@
git/commit foo.c
git/push
.EE
-
.PP
To set a user and email for commits, run:
.IP
@@ -671,41 +649,40 @@
% >$home/lib/git/config echo '
[user]
name = Ori Bernstein
- email = ori@eigenstate.org'
+ email = ori@eigenstate.org
+\&'
.EE
-
.SH FILES
.TP
-$repo/.git
+.B $repo/.git
The full git repository.
.TP
-$repo/.git/config
+.B $repo/.git/config
The configuration file for a repository.
.TP
-$home/lib/git/config
+.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
-/sys/lib/git/config
+.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 replica (1),
+.IR diff (1),
.IR patch (1),
-.IR gitfs (4),
-.I diff3
-
+.IR replica (1),
+.IR gitfs (4)
.SH BUGS
-.PP
Repositories with submodules are effectively read-only.
.PP
There are some missing commands, features, and tools.
.PP
-Git/compat only works within a git repository.
+.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 git/add:
+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}}--
⑨