.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "GITKEEPER 8" .TH GITKEEPER 8 "2016-08-15" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" gitkeeper \- Mirror files between git and an installed location. .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBgk\fR \fI[options]\fR \fBpull\fR \fI[host]\fR .PP \&\fBgk\fR \fI[options]\fR \fBpush\fR \fI[host]\fR .PP \&\fBgk\fR \fI[options]\fR \fBexport\fR \fIgit-ref\fR \fI[host]\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBgitkeeper\fR is a remote administration aid. It enables configuration files to be maintained locally, with a full history of changes, and synchronised on demand with a remote target system. This allows files to still be altered directly on the running system, if and/or when that is needed, with a simple method to get that all back in sync with the archived copy again later. .PP It uses \fBrsync\fR(1) and \fBssh\fR(1) for all operations on the remote hosts. No special configuration beyond permission to use them is required. The use of an \fBssh-agent\fR for managing remote logins may be an advantage though. .PP At its core, \fBgitkeeper\fR is really just a tool for managing bidirectional mirrors, of potentially sparse segments of the remote filesystem, so it's not strictly limited to being used for configuration files, nor is it strictly dependent upon \fBgit\fR(1) aside from the \fBexport\fR option, but those are the primary uses that it was initially designed for. .SH "COMMANDS" .IX Header "COMMANDS" .IP "\fBpull\fR" 8 .IX Item "pull" Pull files from the remote system into the local mirror. This will update the local directory content to match the live system, but it will not commit any files to git or change the local index state in any way. If you wish to commit changes imported in this way, you can just do that with normal git operations. .Sp If the \fIhost\fR parameter is not explicitly specified, then all defined hosts will be pulled. .IP "\fBpush\fR" 8 .IX Item "push" Push files from the local mirror to the remote system. This will push the state of the current working directory, regardless of whether the repository tree is currently clean or dirty. .Sp If the \fIhost\fR parameter is not explicitly specified, then all defined hosts will be pushed. .IP "\fBexport\fR" 8 .IX Item "export" Push files from a historical snapshot of the local mirror to the remote system. This will do a \fBgit archive\fR(1) export of the given \fIgit-ref\fR to a temporary directory, and then perform a \fBpush\fR operation on that tree. It is equivalent to doing a \fBgit checkout\fR of the desired ref, and then doing a \fBpush\fR on that tree state, except it will respect any \fBgitattributes\fR you have set for what will be exported, and it will not change the current working directory state. .Sp If the \fIhost\fR parameter is not explicitly specified, then all hosts defined in the exported configuration will be pushed. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-c, \-\-config\fR \fIfile\fR" 8 .IX Item "-c, --config file" The file describing what should be mirrored and how. If not specified then \&\fIgk.conf\fR will be looked for in the directory that \fBgitkeeper\fR is invoked in. Usually this should be a relative path under that location, but an absolute path is permitted and may be useful in some circumstances. .Sp If the \fBexport\fR command is used, then this file is not read until after the export from git, and relative paths are resolved to files in the exported directory. This is usually what you want since the configuration from the exported snapshot will then be used. If you need to override that for some reason then you can use an absolute path to an alternate configuration file. .IP "\fB\-l, \-\-list\fR" 8 .IX Item "-l, --list" Show the list of host aliases defined in the configuration file. If this is used with the \fBexport\fR command, then the configuration of the exported snapshot will be shown. .IP "\fB\-\-init\fR" 8 .IX Item "--init" Create a skeleton configuration file. This is a convenience to get an initial configuration when bootstrapping a new mirror. .IP "\fB\-C, \-\-chdir\fR \fIdirectory\fR" 8 .IX Item "-C, --chdir directory" Change to the given directory before running \fBgitkeeper\fR. Normally you would just run it from the top level directory of the mirror, but this permits use from elsewhere in a similar way to what \f(CW\*(C`make \-C directory\*(C'\fR allows. .IP "\fB\-\-destdir\fR \fIdirectory\fR" 8 .IX Item "--destdir directory" Prefix the remote paths to an alternate file system root. This always changes only the remote path, regardless of whether a \fBpush\fR or \fBpull\fR operation is being performed. It acts like the \f(CW\*(C`DESTDIR\*(C'\fR option for \f(CW\*(C`make install\*(C'\fR and allows mirroring files to and from an alternative filesystem location but with the same subdirectory structure as what they would normally have. .Sp You can use this to export files to a chroot, or to a temporary directory somewhere, so that they can be examined without replacing the real files on the remote system. .IP "\fB\-u, \-\-user\fR" 8 .IX Item "-u, --user" Override the \fBremote_user\fR option from the configuration file for access to the remote host. There probably aren't many good reasons to ever use this option, it's a pretty blunt hammer which will override it everywhere, but it may be useful for exporting a mirror to some machine or location where it isn't usually expected to go. .IP "\fB\-n, \-\-dry\-run\fR" 8 .IX Item "-n, --dry-run" Don't actually copy any files, just show what would be done if this was a live run. If this is used with the \fBexport\fR command, then the dry run will be performed on the requested snapshot. .IP "\fB\-v, \-\-verbose\fR" 8 .IX Item "-v, --verbose" Show more detail about what is being done. This option may be passed multiple times to increase the level of verbosity even further. .Sp If passed along with \fB\-\-help\fR then more verbose documentation will be shown. .IP "\fB\-?, \-\-help\fR" 8 .IX Item "-?, --help" Show this help, again. .SH "CONFIGURATION" .IX Header "CONFIGURATION" The \fBgitkeeper\fR configuration file is expected to contain a single \s-1JSON\s0 Object, which will be parsed by perl's \s-1JSON::XS\s0 in its relaxed mode (which allows trailing commas after the final element of an array or object, and '#'\-comments anywhere that whitespace would be permitted). .SS "Global options" .IX Subsection "Global options" There is only one required member of the top level object, though other options may also be specified there to be inherited as defaults if not overridden for a host or one of its sync sets. .IP "\fBhosts\fR" 8 .IX Item "hosts" The \fBhosts\fR member defines a \s-1JSON\s0 object in which each member is a host name alias that may be passed as the \fIhost\fR parameter to \fBgitkeeper\fR. The alias names are not used for any other purpose than as the \fIhost\fR identifier, and may be any \s-1JSON\s0 string value. No other options may be included directly in the \fBhosts\fR section. .PP .Vb 6 \& { \& "hosts": { \& "host1": { ... }, \& "host2": { ... } \& } \& } .Ve .SS "Per-host options" .IX Subsection "Per-host options" There are two required members which must be specified directly for each host alias object. Other options may also be specified there which will override a global default for that host and be inherited as defaults for its sync sets, if not also overridden there. .IP "\fBaddress\fR" 8 .IX Item "address" The \fBaddress\fR member is a \s-1JSON\s0 string value, that defines the hostname or \s-1IP\s0 address used when connecting to the remote system. It must be a valid string that can be passed as the host part of a remote \fBrsync\fR(1) path. It should not contain a \fIuser\fR part (that should instead be set with the \fBremote_user\fR option), but may contain a port specification. .IP "\fBsync\fR" 8 .IX Item "sync" The \fBsync\fR member is a \s-1JSON\s0 array of objects. It must contain at least one object, but there is no upper bound to the number which may be included. Each of the objects in the \fBsync\fR array define a mapping from a \fBremote_root\fR to a \fBlocal_root\fR, the paths which will be mirrored under those roots, and the \&\fBrsync\fR options which will be applied when transferring them. .PP .Vb 4 \& "host1": { \& "address": "myhost.mydomain.org", \& "sync": [ { ... }, { ... } ] \& } .Ve .SS "Sync set options" .IX Subsection "Sync set options" Each object in the \fBsync\fR array has one required member that must be specified directly in it. Other options may also be specified there which will override the global and host defaults, and some of those options must also be defined in at least one of those places for each sync set. .IP "\fBpaths\fR" 8 .IX Item "paths" The \fBpaths\fR member is an array of \s-1JSON\s0 string values which specify the files and/or directories under the \fBremote_root\fR which will be mirrored with their full directory structure. They may contain shell wildcards, but cannot contain brace expansions if the \fBrsync \-\-protect\-args\fR option is used. .Sp They must all be relative paths (ie. they must not begin with a '/'). .PP .Vb 5 \& "sync": [ \& { \& "paths": [ "file1", "dir1", "dir2/subdir", "dir3/*.conf" ] \& } \& ] .Ve .SS "Required options" .IX Subsection "Required options" The following options must be defined for every sync set, though they may be configured in either the top level object as global defaults, in the host alias object for per-host defaults, or in the sync object itself. .IP "\fBlocal_root\fR" 8 .IX Item "local_root" A \s-1JSON\s0 string value that defines the local directory which remote \fBpaths\fR will be mirrored under. This must be a relative path, which itself is rooted to the directory under which \fBgitkeeper\fR is invoked. .Sp As a sanity check against accidents, this directory must already exist. .IP "\fBremote_root\fR" 8 .IX Item "remote_root" A \s-1JSON\s0 string value which defines the location on the remote system that the specified \fBpaths\fR are relative to. This may be an absolute or relative path. A relative path will be rooted to the home directory of the \fBremote_user\fR. A value of "" may be used to specify the home directory of the \fBremote_user\fR. .SS "Additional options" .IX Subsection "Additional options" The following options may be defined as global or per-host defaults, or set explicitly in each sync set. It is not an error for them not to be set, and a higher level default may be 'unset' by overriding it with an empty value. .IP "\fBremote_user\fR" 8 .IX Item "remote_user" A \s-1JSON\s0 string which defines the username to use for access to the remote host. If not set, then the ssh default for the remote system will be used (as configured by .ssh/config or similar). .IP "\fBrsync_opts\fR" 8 .IX Item "rsync_opts" A \s-1JSON\s0 array of string values containing options to be passed to all invocations of \fBrsync\fR, for both \fBpush\fR and \fBpull\fR operations. No word splitting or shell quote stripping is done on the values used here, so each option must be its own array element. .Sp Note that the \fB\-\-relative\fR option is passed to \fBrsync\fR(1) by default for all invocations and does not need to be included in this set. If you really don't want that option for some reason, and understand the consequences of not passing it for this use, you can disable it with \fB\-\-no\-relative\fR, but there's probably no good reason to ever do that here. .Sp .Vb 4 \& "rsync_opts": [ "\-\-prune\-empty\-dirs", \& "\-\-delete\-excluded", \& "\-\-filter=protect .s[a\-w][a\-z]" \& ] .Ve .IP "\fBrsync_pull_opts\fR" 8 .IX Item "rsync_pull_opts" Similar to \fBrsync_opts\fR above, but options specified in this array are appended to those only for \fBpull\fR operations. .IP "\fBrsync_push_opts\fR" 8 .IX Item "rsync_push_opts" Similar to \fBrsync_opts\fR above, but options specified in this array are appended to those only for \fBpush\fR operations. .IP "\fBrsync_include\fR" 8 .IX Item "rsync_include" A \s-1JSON\s0 array of string values which will be passed to \fBrsync\fR(1) as \fB\-\-include\fR options. This is a convenience which is eqivalent to adding those to \fBrsync_opts\fR ie. the following configurations would be identical in their operation if no other ordering constraints for the filter rules applied. .Sp .Vb 2 \& "rsync_opts": [ "\-\-include=.s[a\-w][a\-z]/" ] \& "rsync_include": [ ".s[a\-w][a\-z]/" ] .Ve .IP "\fBrsync_exclude\fR" 8 .IX Item "rsync_exclude" A \s-1JSON\s0 array of string values which will be passed to \fBrsync\fR(1) as \fB\-\-exclude\fR options. This is the same as \fBrsync_include\fR above, except for excludes. .IP "\fBrsync_filter\fR" 8 .IX Item "rsync_filter" A \s-1JSON\s0 array of string values which will be passed to \fBrsync\fR(1) as \fB\-\-filter\fR options. This is similar to the include and exclude options above, except it allows the full range of \fBrsync\fR filter rules to be used. .IP "\fBrsync_pull_filter\fR" 8 .IX Item "rsync_pull_filter" A \s-1JSON\s0 array of string values which will be passed to \fBrsync\fR(1) as \fB\-\-filter\fR options (in addition to the include, exclude, and filter options above) only for \&\fBpull\fR operations. .IP "\fBrsync_push_filter\fR" 8 .IX Item "rsync_push_filter" A \s-1JSON\s0 array of string values which will be passed to \fBrsync\fR(1) as \fB\-\-filter\fR options (in addition to the include, exclude, and filter options above) only for \&\fBpush\fR operations. .IP "\fBchown\fR" 8 .IX Item "chown" A \s-1JSON\s0 string value which will be passed to \fBrsync\fR as the \fB\-\-chown\fR option for \fBpush\fR operations to set file and directory ownership on the remote host. If this option is used, the \fB\-\-owner\fR and \fB\-\-group\fR options will automatically added too, otherwise it would have no effect. You must have superuser privilege on the remote host for this to work. .Sp .Vb 1 \& "chown": "root:bind" .Ve .IP "\fBchmod\fR" 8 .IX Item "chmod" A \s-1JSON\s0 string value which will be passed to \fBrsync\fR as the \fB\-\-chmod\fR option for \fBpush\fR operations to set file and directory permissions on the remote host. If this option is used, the \fB\-\-perms\fR option will automatically added too, otherwise it would have no effect. Valid values here are anything that the \&\fBrsync\fR option would accept. .Sp .Vb 1 \& "chmod": "D2755,F664" .Ve .SS "Pre\- and Post\- command hooks" .IX Subsection "Pre- and Post- command hooks" The following options may be used to execute arbitrary commands before and/or after a \fBpull\fR or \fBpush\fR operation. The commands are executed on the local host, in the directory that \fBgitkeeper\fR was invoked in, as the user which \&\fBgitkeeper\fR was invoked as. They can be used to perform operations on the remote host by simply invoking \fBssh\fR(1) or similar themselves. .IP "\fBpull_pre_command\fR" 8 .IX Item "pull_pre_command" .PD 0 .IP "\fBpush_pre_command\fR" 8 .IX Item "push_pre_command" .IP "\fBpull_post_command\fR" 8 .IX Item "pull_post_command" .IP "\fBpush_post_command\fR" 8 .IX Item "push_post_command" .PD A \s-1JSON\s0 array of string values containing the command to execute and the options to pass to it. This will be passed as an array to the perl \fB\f(BIsystem()\fB\fR command, so if the array contains multiple elements, then no word splitting or other shell interpretation will be performed. If it is a single string, then it will instead be passed to the local shell, with all the caveats that accompany doing that. .Sp If the pre-command fails, then no transfer will take place. If the transfer fails for some reason then the post-command will not be executed. .Sp That might change later if we let this get more complex and begin passing status and other variables to the commands that are invoked, but at this stage, that isn't really needed for any current use we have, so I'm not going to complicate things now in anticipation of what later uses might require. .SH "FILES" .IX Header "FILES" .IP "\fB./gk.conf\fR" 8 .IX Item "./gk.conf" The default configuration file. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBgit\fR(1), \&\fBrsync\fR(1), \&\fBssh\fR(1), \&\fBssh-agent\fR(1). .SH "AUTHOR" .IX Header "AUTHOR" \&\fBgitkeeper\fR was written by Ron .