.\" Automatically generated by Pandoc 1.17.2 .\" .TH "GIT\-FTP" "1" "2016\-12\-03" "git\-ftp User Manual" "" .hy .SH NAME .PP Git\-ftp \- Git powered FTP client written as shell script. .SH SYNOPSIS .PP \f[I]git\-ftp\f[] [] [] .SH DESCRIPTION .PP Git\-ftp is an FTP client using Git (http://git-scm.org) to determine which local files to upload or which files to delete on the remote host. .PP It saves the deployed state by uploading the SHA1 hash in the \f[C]\&.git\-ftp.log\f[] file. There is no need for Git to be installed on the remote host. .PP Even if you play with different branches, git\-ftp knows which files are different and handles only those files. That saves time and bandwidth. .SH ACTIONS .TP .B \f[C]init\f[] Uploads all git\-tracked non\-ignored files to the remote server and creates the \f[C]\&.git\-ftp.log\f[] file containing the SHA1 of the latest commit. .RS .RE .TP .B \f[C]catchup\f[] Creates or updates the \f[C]\&.git\-ftp.log\f[] file on the remote host. It assumes that you uploaded all other files already. You might have done that with another program. .RS .RE .TP .B \f[C]push\f[] Uploads files that have changed and deletes files that have been deleted since the last upload. .RS .RE .TP .B \f[C]download\f[] (EXPERIMENTAL) Downloads changes from the remote host into your working tree. This feature needs lftp to be installed and does not use any power of Git. WARNING: It can delete local untracked files that are not listed in your \f[C]\&.git\-ftp\-ignore\f[] file. .RS .RE .TP .B \f[C]pull\f[] (EXPERIMENTAL) Downloads changes from the remote host into a separate commit and merges that into your current branch. This feature needs lftp to be installed. .RS .RE .TP .B \f[C]snapshot\f[] (EXPERIMENTAL) Downloads files into a new Git repository. Takes an additional argument as local destination directory. Example: `git\-ftp snapshot ftp://example.com/public_html projects/example` This feature needs lftp to be installed. .RS .RE .TP .B \f[C]show\f[] Downloads last uploaded SHA1 from log and hooks `git show`. .RS .RE .TP .B \f[C]log\f[] Downloads last uploaded SHA1 from log and hooks `git log`. .RS .RE .TP .B \f[C]add\-scope\ \f[] Creates a new scope (e.g. dev, production, testing, foobar). This is a wrapper action over git\-config. See \f[B]SCOPES\f[] section for more information. .RS .RE .TP .B \f[C]remove\-scope\ \f[] Remove a scope. .RS .RE .TP .B \f[C]help\f[] Shows a help screen. .RS .RE .SH OPTIONS .TP .B \f[C]\-u\ [username]\f[], \f[C]\-\-user\ [username]\f[] FTP login name. If no argument is given, local user will be taken. .RS .RE .TP .B \f[C]\-p\ [password]\f[], \f[C]\-\-passwd\ [password]\f[] FTP password. See \f[C]\-P\f[] for interactive password prompt. .RS .RE .TP .B \f[C]\-P\f[], \f[C]\-\-ask\-passwd\f[] Ask for FTP password interactively. .RS .RE .TP .B \f[C]\-k\ [[user]\@[account]]\f[], \f[C]\-\-keychain\ [[user]\@[account]]\f[] FTP password from KeyChain (Mac OS X only). .RS .RE .TP .B \f[C]\-a\f[], \f[C]\-\-all\f[] Uploads all files of current Git checkout. .RS .RE .TP .B \f[C]\-A\f[], \f[C]\-\-active\f[] Uses FTP active mode. .RS .RE .TP .B \f[C]\-b\ [branch]\f[], \f[C]\-\-branch\ [branch]\f[] Push a specific branch .RS .RE .TP .B \f[C]\-s\ [scope]\f[], \f[C]\-\-scope\ [scope]\f[] Using a scope (e.g. dev, production, testing, foobar). See \f[B]SCOPE\f[] and \f[B]DEFAULTS\f[] section for more information. .RS .RE .TP .B \f[C]\-l\f[], \f[C]\-\-lock\f[] Enable remote locking. .RS .RE .TP .B \f[C]\-D\f[], \f[C]\-\-dry\-run\f[] Does not upload or delete anything, but tries to get the \f[C]\&.git\-ftp.log\f[] file from remote host. .RS .RE .TP .B \f[C]\-f\f[], \f[C]\-\-force\f[] Does not ask any questions, it just does. .RS .RE .TP .B \f[C]\-n\f[], \f[C]\-\-silent\f[] Be silent. .RS .RE .TP .B \f[C]\-h\f[], \f[C]\-\-help\f[] Prints some usage information. .RS .RE .TP .B \f[C]\-v\f[], \f[C]\-\-verbose\f[] Be verbose. .RS .RE .TP .B \f[C]\-vv\f[] Be as verbose as possible. Useful for debug information. .RS .RE .TP .B \f[C]\-\-remote\-root\f[] Specifies the remote root directory to deploy to. The remote path in the URL is ignored. .RS .RE .TP .B \f[C]\-\-syncroot\f[] Specifies a local directory to sync from as if it were the git project root path. .RS .RE .TP .B \f[C]\-\-key\f[] SSH private key file name. .RS .RE .TP .B \f[C]\-\-pubkey\f[] SSH public key file name. Used with \-\-key option. .RS .RE .TP .B \f[C]\-\-insecure\f[] Don\[aq]t verify server\[aq]s certificate. .RS .RE .TP .B \f[C]\-\-cacert\ \f[] Use as CA certificate store. Useful when a server has a self\-signed certificate. .RS .RE .TP .B \f[C]\-\-disable\-epsv\f[] Tell curl to disable the use of the EPSV command when doing passive FTP transfers. Curl will normally always first attempt to use EPSV before PASV, but with this option, it will not try using EPSV. .RS .RE .TP .B \f[C]\-\-no\-commit\f[] Stop while merging downloaded changes during the pull action. .RS .RE .TP .B \f[C]\-\-changed\-only\f[] During the ftp mirror operation during a pull command, consider only the files changed since the deployed commit. .RS .RE .TP .B \f[C]\-\-no\-verify\f[] Bypass the pre\-ftp\-push hook. See \f[B]HOOKS\f[] section. .RS .RE .TP .B \f[C]\-\-version\f[] Prints version. .RS .RE .SH URL .PP The scheme of an URL is what you would expect .IP .nf \f[C] protocol://host.domain.tld:port/path \f[] .fi .PP Below a full featured URL to \f[I]host.example.com\f[] on port \f[I]2121\f[] to path \f[I]mypath\f[] using protocol \f[I]ftp\f[]: .IP .nf \f[C] ftp://host.example.com:2121/mypath \f[] .fi .PP But, there is not just FTP. Supported protocols are: .TP .B \f[C]ftp://...\f[] FTP (default if no protocol is set) .RS .RE .TP .B \f[C]sftp://...\f[] SFTP .RS .RE .TP .B \f[C]ftps://...\f[] FTPS .RS .RE .TP .B \f[C]ftpes://...\f[] FTP over explicit SSL (FTPES) protocol .RS .RE .SH DEFAULTS .PP Don\[aq]t repeat yourself. Setting config defaults for git\-ftp in .git/config .IP .nf \f[C] $\ git\ config\ git\-ftp.<(url|user|password|syncroot|cacert|keychain)>\ \f[] .fi .PP Everyone likes examples: .IP .nf \f[C] $\ git\ config\ git\-ftp.user\ john $\ git\ config\ git\-ftp.url\ ftp.example.com $\ git\ config\ git\-ftp.password\ secr3t $\ git\ config\ git\-ftp.syncroot\ path/dir $\ git\ config\ git\-ftp.cacert\ caCertStore $\ git\ config\ git\-ftp.deployedsha1file\ mySHA1File $\ git\ config\ git\-ftp.insecure\ 1 $\ git\ config\ git\-ftp.key\ ~/.ssh/id_rsa $\ git\ config\ git\-ftp.keychain\ user\@example.com \f[] .fi .PP After setting those defaults, push to \f[I]john\@ftp.example.com\f[] is as simple as .IP .nf \f[C] $\ git\ ftp\ push \f[] .fi .SH SCOPES .PP Need different config defaults per each system or environment? Use the so called scope feature. .PP Useful if you use multi environment development. Like a development, testing and a production environment. .IP .nf \f[C] $\ git\ config\ git\-ftp..<(url|user|password|syncroot|cacert)>\ \f[] .fi .PP So in the case below you would set a testing scope and a production scope. .PP Here we set the params for the scope "testing" .IP .nf \f[C] $\ git\ config\ git\-ftp.testing.url\ ftp.testing.com:8080/foobar\-path $\ git\ config\ git\-ftp.testing.password\ simp3l \f[] .fi .PP Here we set the params for the scope "production" .IP .nf \f[C] $\ git\ config\ git\-ftp.production.user\ manager $\ git\ config\ git\-ftp.production.url\ live.example.com $\ git\ config\ git\-ftp.production.password\ n0tThatSimp3l \f[] .fi .PP Pushing to scope \f[I]testing\f[] alias \f[I]john\@ftp.testing.com:8080/foobar\-path\f[] using password \f[I]simp3l\f[] .IP .nf \f[C] $\ git\ ftp\ push\ \-s\ testing \f[] .fi .PP \f[I]Note:\f[] The \f[B]SCOPE\f[] feature can be mixed with the \f[B]DEFAULTS\f[] feature. Because we didn\[aq]t set the user for this scope, git\-ftp uses \f[I]john\f[] as user as set before in \f[B]DEFAULTS\f[]. .PP Pushing to scope \f[I]production\f[] alias \f[I]manager\@live.example.com\f[] using password \f[I]n0tThatSimp3l\f[] .IP .nf \f[C] $\ git\ ftp\ push\ \-s\ production \f[] .fi .PP \f[I]Hint:\f[] If your scope name is identical with your branch name. You can skip the scope argument, e.g. if your current branch is "production": .IP .nf \f[C] $\ git\ ftp\ push\ \-s \f[] .fi .PP You can also create scopes using the add\-scope action. All settings can be defined in the URL. Here we create the \f[I]production\f[] scope using add\-scope .IP .nf \f[C] $\ git\ ftp\ add\-scope\ production\ ftp://manager:n0tThatSimp3l\@live.example.com/foobar\-path \f[] .fi .PP Deleting scopes is easy using the \f[C]remove\-scope\f[] action. .IP .nf \f[C] $\ git\ ftp\ remove\-scope\ production \f[] .fi .SH IGNORING FILES TO BE SYNCED .PP Add patterns to \f[C]\&.git\-ftp\-ignore\f[] and all matching file names will be ignored. The patterns are interpreted as shell glob patterns. .PP For example, ignoring everything in a directory named \f[C]config\f[]: .IP .nf \f[C] config/* \f[] .fi .PP Ignoring all files having extension \f[C]\&.txt\f[]: .IP .nf \f[C] *.txt \f[] .fi .PP Ignoring a single file called \f[C]foobar.txt\f[]: .IP .nf \f[C] foobar.txt \f[] .fi .SH SYNCING UNTRACKED FILES .PP The \f[C]\&.git\-ftp\-include\f[] file specifies intentionally untracked files that Git\-ftp should upload. If you have a file that should always be uploaded, add a line beginning with ! followed by the file\[aq]s name. For example, if you have a file called VERSION.txt then add the following line: .IP .nf \f[C] !VERSION.txt \f[] .fi .PP If you have a file that should be uploaded whenever a tracked file changes, add a line beginning with the untracked file\[aq]s name followed by a colon and the tracked file\[aq]s name. For example, if you have a CSS file compiled from an SCSS file then add the following line: .IP .nf \f[C] css/style.css:scss/style.scss \f[] .fi .PP If you have multiple source files, you can add multiple lines for each of them. Whenever one of the tracked files changes, the upload of the paired untracked file will be triggered. .IP .nf \f[C] css/style.css:scss/style.scss css/style.css:scss/mixins.scss \f[] .fi .PP If a local untracked file is deleted, a paired tracked file will trigger the deletion of the remote file on the server. .PP When using the \f[C]\-\-syncroot\f[] option, all paths are relative to the set syncroot. If your source file is outside the syncroot, add a / and define a path relative to the Git working directory. .IP .nf \f[C] #\ upload\ "dist/style.css"\ with\ syncroot\ "dist" style.css:/style.scss \f[] .fi .PP It is also possible to upload whole directories. For example, if you use a package manager like composer, you can upload all vendor packages when the file composer.lock changes: .IP .nf \f[C] vendor/:composer.lock \f[] .fi .PP But keep in mind that this will upload all files in the vendor folder, even those that are on the server already. And it will not delete files from that directory if local files are deleted. .SH DOWNLOADING FILES (EXPERIMENTAL) .PP \f[B]WARNING:\f[] It can delete local untracked files that are not listed in your \f[C]\&.git\-ftp\-ignore\f[] file. .PP You can use git\-ftp to download from the remote host into your repository. You will need to install the lftp command line tool for that. .IP .nf \f[C] git\ ftp\ download \f[] .fi .PP It uses lftp\[aq]s mirror command to download all files that are different on the remote host. You can inspect the changes with git\-diff. But if you have some local commits that have not been uploaded to the remote host, you may not compare to the right version. You need to compare the downloaded files to the commit that was uploaded last. This magic is done automatically by .IP .nf \f[C] git\ ftp\ pull \f[] .fi .PP It does the following steps for you: .IP .nf \f[C] git\ checkout\ git\ ftp\ download git\ add\ \-\-all git\ commit\ \-m\ \[aq][git\-ftp]\ remotely\ untracked\ modifications\[aq] git\ ftp\ catchup git\ checkout\ git\ merge\ \f[] .fi .PP If you want to inspect the downloaded changes before merging them into your current branch, add the option \f[C]\-\-no\-commit\f[]. It will stop during the merge at the end of the pull action. You can inspect the merge result first and can then decide to continue or abort. .IP .nf \f[C] git\ ftp\ pull\ \-\-no\-commit #\ inspect\ the\ result\ and\ commit\ them git\ commit #\ or\ abort\ the\ merge git\ merge\ \-\-abort \f[] .fi .PP If you abort the merge, the downloaded changes will stay in an unreferenced commit until the Git garbage collector is run. The commit id will be printed so that you can tag it or create a new branch. .SH HOOKS (EXPERIMENTAL) .PP \f[B]This feature is experimental. The interface may change.\f[] .PP Git\-ftp supports client\-side hook scripts during the init and the push action. .PP \f[C]pre\-ftp\-push\f[] is called just before the upload to the server starts, but after the changeset of files was generated. It can be bypassed with the \-\-no\-verify option. .PP The hook is called with four parameters. The first is the used scope or the host name if no scope is used. The second parameter is the destination URL. The third is the local commit id which is going to be uploaded and the fourth is the remote commit id on the server which is going to be updated. .PP The standard input is a list of all filenames to sync. Each file is preceeded by A or D followed by a space. A means that this file is scheduled for upload, D means it\[aq]s scheduled for deletion. All entries are separated by the NUL byte. This list is different to git diff, because it has been changed by the rules of the \f[C]\&.git\-ftp\-include\f[] file and the \f[C]\&.git\-ftp\-ignore\f[] file. .PP Exiting with non\-zero status from this script causes Git\-ftp to abort and exit with status 9. .PP An example script is: .IP .nf \f[C] #!/bin/bash # #\ An\ example\ hook\ script\ to\ verify\ what\ is\ about\ to\ be\ uploaded. # #\ Called\ by\ "git\ ftp\ push"\ after\ it\ has\ checked\ the\ remote\ status,\ but\ before #\ anything\ has\ been\ pushed.\ If\ this\ script\ exits\ with\ a\ non\-zero\ status\ nothing #\ will\ be\ pushed. # #\ This\ hook\ is\ called\ with\ the\ following\ parameters: # #\ $1\ \-\-\ Scope\ name\ if\ set\ or\ host\ name\ of\ the\ remote #\ $2\ \-\-\ URL\ to\ which\ the\ upload\ is\ being\ done #\ $3\ \-\-\ Local\ commit\ id\ which\ is\ being\ uploaded #\ $4\ \-\-\ Remote\ commit\ id\ which\ is\ on\ the\ server # #\ Information\ about\ the\ files\ which\ are\ being\ uploaded\ or\ deleted\ is\ supplied #\ as\ NUL\ separated\ entries\ to\ the\ standard\ input\ in\ the\ form: # #\ \ \ \ # #\ The\ status\ is\ either\ A\ for\ upload\ or\ D\ for\ delete.\ The\ path\ contains\ the #\ path\ to\ the\ local\ file.\ It\ contains\ the\ syncroot\ if\ set. # #\ This\ sample\ shows\ how\ to\ prevent\ upload\ of\ files\ containing\ the\ word\ TODO. remote="$1" url="$2" local_sha="$3" remote_sha="$4" while\ read\ \-r\ \-d\ \[aq]\[aq]\ status\ file do \ \ \ \ if\ [\ "$status"\ =\ "A"\ ] \ \ \ \ then \ \ \ \ \ \ \ \ if\ grep\ \[aq]TODO\[aq]\ "$file";\ then \ \ \ \ \ \ \ \ \ \ \ \ echo\ "TODO\ found\ in\ file\ $file,\ not\ uploading." \ \ \ \ \ \ \ \ \ \ \ \ exit\ 1 \ \ \ \ \ \ \ \ fi \ \ \ \ fi done exit\ 0 \f[] .fi .PP \f[C]post\-ftp\-push\f[] is called after the transfer has been finished. The standard input is empty, but the parameters are the same as given to the \f[C]pre\-ftp\-push\f[] hook. This hook is \f[B]not\f[] bypassed by the \-\-no\-verify option. It is meant primarily for notification and its exit status does not have any effect. .SH NETRC .PP In the backend, Git\-ftp uses curl. This means \f[C]~/.netrc\f[] could be used beside the other options of Git\-ftp to authenticate. .IP .nf \f[C] $\ editor\ ~/.netrc machine\ ftp.example.com login\ john password\ SECRET \f[] .fi .SH EXIT CODES .PP There are a bunch of different error codes and their corresponding error messages that may appear during bad conditions. At the time of this writing, the exit codes are: .TP .B \f[C]1\f[] Unknown error .RS .RE .TP .B \f[C]2\f[] Wrong Usage .RS .RE .TP .B \f[C]3\f[] Missing arguments .RS .RE .TP .B \f[C]4\f[] Error while uploading .RS .RE .TP .B \f[C]5\f[] Error while downloading .RS .RE .TP .B \f[C]6\f[] Unknown protocol .RS .RE .TP .B \f[C]7\f[] Remote locked .RS .RE .TP .B \f[C]8\f[] Not a Git project .RS .RE .TP .B \f[C]9\f[] The \f[C]pre\-ftp\-push\f[] hook failed .RS .RE .TP .B \f[C]10\f[] A local file operation like \f[C]cd\f[] or \f[C]mkdir\f[] failed .RS .RE .SH KNOWN ISSUES & BUGS .PP The upstream BTS can be found at . .SH AUTHORS .PP Git\-ftp was started by Rene Moser and is currently maintained by Maikel Linke. Numerous conributions have come from Github users. See the AUTHORS file for an incomplete list of contributors.