add a manpage describing the patch formatHEADmaster

It also has some ideas for additional meta-data

Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>

1 files changed, 55 insertions, 0 deletions

diff --git a/ug.7 b/ug.7
new file mode 100644
index 0000000..31231c3
--- /dev/null
+++ b/ug.7
@@ -0,0 +1,55 @@
+.TH ug 7 2011-04-27 
+.SH NAME
+ubergit \- patch manager for git
+.SH SYNOPSIS
+.B ug \-\-version
+.br
+.B ug \-\-help
+.br
+.B ug [\-\-debug]
+.I command
+\&...
+.SH "PATCH FORMAT"
+ubergit stores patches as ordinary git trees/commits with some metadata in the
+directory
+.IR .ubergit .
+There are two different types of ubergit trees: topics and bases.
+A "base" contains (at least) a non-empty list of dependencies in
+.IR .ubergit/deps ;
+one sha1 hash per line. A "topic" contains (at least) a sha1 hash in the file
+.I .ubergit/base
+and a commit log in
+.IR .ubergit/msg .
+
+A topic corresponds to a single patch, the diff between the topic and its base.
+
+To export a topic into an ordinary git tree, the following is done:
+.IP \[bu] 2
+for the topic's base recusively export all dependencies
+.RI ( .ubergit/deps );
+.IP \[bu]
+merge all exported dependencies (=: "exported base")
+.IP \[bu]
+add the patch on top of the exported base with the commit log taken from
+.IR .ubergit/msg .
+.\" See
+.\" .BR ug-export (1)
+.\" for further info
+
+.SS Further (unimplemented) metadata
+.IP \[bu] 2
+.I .ubergit/author
+could be used to specify the author of the patch. (Format? Encoding?)
+.IP \[bu]
+.I .ubergit/series
+could be used to group topics into series. (Contains a name or a list of names?)
+.IP \[bu]
+.IR .ubergit/to ;
+.I .ubergit/cc
+and
+.I .ubergit/bcc
+to implement
+.BR ug-send-email (1).
+
+.SH "SEE ALSO"
+.BR git (1)