git-meta.1

'\" t
.\"     Title: git-meta
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 01/04/2016
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "GIT\-META" "1" "01/04/2016" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
git-meta \- Handle file meta information within git
.SH "SYNOPSIS"
.sp
git\-meta [ options ] command
.SH "DESCRIPTION"
.sp
Git (currently) cannot handle file system meta information such as permissions, last modification time or ownership (both user and group)\&. Here comes git\-meta to fix this in some cases where these informations are mandatory or simply useful\&.
.sp
All informations are stored in a \&.gitmeta file managed itself by git\&.
.sp
Using git hooks may automate the backup and restore process\&.
.SH "OPTIONS"
.PP
\-\-data DATA
.RS 4
Set the
git\-meta
database file (default:
\fI\&.gitmeta\fR)\&.
.RE
.PP
\-f|\-\-force
.RS 4
Force writing data even if no modification has been done in the git tree\&. By default
git\-meta
does not run if no modification has been done to prevent from massive git change set creation\&.
.RE
.PP
\-h|\-\-help
.RS 4
Display help screen\&.
.RE
.PP
\-a|\-\-add\-to\-git
.RS 4
Add database to the git commit list\&.
.RE
.PP
\-O|\-\-owner
.RS 4
Store symbolic file ownership to the database\&.
.RE
.PP
\-o|\-\-numeric\-owner
.RS 4
Store numeric file ownership to the database\&.
.RE
.PP
\-P|\-\-skip\-perms
.RS 4
Skip file perms during restore\&.
.RE
.PP
\-M|\-\-skip\-mtime
.RS 4
Skip file mtime during store/restore operations\&. The mtime is not written into the database\&.
.RE
.PP
\-U|\-\-skip\-user
.RS 4
Skip file owner during restore\&.
.RE
.PP
\-G|\-\-skip\-group
.RS 4
Skip group owner during restore\&.
.RE
.PP
\-i|\-\-ignore BRANCH
.RS 4
Branch on witch
git\-meta
is ignored\&. This is treated as a regexp\&. This option can be specified several times\&. if not specfied, values are search in the
meta\&.ignore
git configuration key\&.
.RE
.SH "COMMANDS"
.PP
get
.RS 4
Store metadata to database\&.
.RE
.PP
set
.RS 4
Restore metadata from database\&.
.RE
.PP
dump
.RS 4
Dump metadata from database\&.
.RE
.PP
init
.RS 4
Create hooks in git hooks directory\&.
.RE
.SH "DATABASE FORMAT"
.sp
The database format is quiet simple\&. It consists of a JSON dump of a dictionnary for which the file name is the key and the file attributes are the values\&. dictionnary\&.
.SS "Dictionnary format"
.sp
The key is composed of the full filename path starting from the git repository root\&.
.sp
Each values are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
mode: the file permissions in decimal format\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
mtime: the file mtime in seconds since Epoch\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
uid: the file owner (in numerical or symbolic format)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
gid: the file group (in numerical or symbolic format)\&.
.RE
.SS "File ownership"
.sp
File ownership (both owner and group) are either:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Not stored at all if neighter the
\fI\-o\fR
nor
\fI\-O\fR
option is given\&. This might be used if the files ownership may change from one system to an other\&. Generally this should be used in almost all cases\&. Otherwise a large amount of changesets could pollute git commits\&. In that case the last 2 fields (both owner and group) of each record are not present in the database\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Stored in symbolic format if
\fI\-O\fR
is given\&. This option should be used if symbolic ownership are the same in all systems (for keeping track of
\fI/etc\fR
changes for example)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Stored in numerical format if
\fI\-o\fR
is given\&. This option should be used if numerical ownerships are the same in all systems\&.
.RE
.SH "USING WITH GIT HOOKS"
.sp
Manual use git\-meta is not that much handy\&. It can be configured to be used directly withing githooks(5), specially \fBpre\-commit\fR for the backup and \fBpost\-merge\fR for the restore\&.
.SS "pre\-commit example"
.sp
.if n \{\
.RS 4
.\}
.nf
#!/bin/sh

git meta \-a get || true
.fi
.if n \{\
.RE
.\}
.SS "post\-merge example"
.sp
.if n \{\
.RS 4
.\}
.nf
#!/bin/sh

git meta set || true
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
git(1), githooks(5)\&.
.SH "HISTORY"
.PP
2014/04/24
.RS 4
Add ignore option
.RE
.PP
2014/03/02
.RS 4
Rewite script in python
.RE
.PP
2011/09/11
.RS 4
Add init command\&.
.RE
.PP
2011/03/26
.RS 4
First public release\&.
.RE
.SH "BUGS"
.sp
No time to include bugs, command actions might seldom lead astray user\(cqs assumption\&.
.SH "AUTHORS"
.sp
git\-meta is written by S\('ebastien Gross <seb\(buɑƬ\(buchezwam\(buɖɵʈ\(buorg>\&.
.SH "COPYRIGHT"
.sp
Copyright \(co 2011\-2014 S\('ebastien Gross <seb\(buɑƬ\(buchezwam\(buɖɵʈ\(buorg>\&.
.sp
Relased under WTFPL (\m[blue]\fBhttp://sam\&.zoy\&.org/wtfpl/COPYING\fR\m[])\&.