Provided by: git-ftp_1.6.0+dfsg-1_all 
NAME
Git-ftp - Git powered FTP client written as shell script.
SYNOPSIS
git-ftp <action> [<options>] [<url>]
DESCRIPTION
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.
It saves the deployed state by uploading the SHA1 hash in the .git-ftp.log file. There is
no need for Git to be installed on the remote host.
Even if you play with different branches, git-ftp knows which files are different and
handles only those files. That saves time and bandwidth.
ACTIONS
init Uploads all git-tracked non-ignored files to the remote server and creates the
.git-ftp.log file containing the SHA1 of the latest commit.
catchup
Creates or updates the .git-ftp.log file on the remote host. It assumes that you
uploaded all other files already. You might have done that with another program.
push Uploads files that have changed and deletes files that have been deleted since the
last upload. If you are using GIT LFS, this uploads LFS link files, not large
files (stored on LFS server). To upload the LFS tracked files, run git lfs pull
before git ftp push: LFS link files will be replaced with large files so they can
be uploaded.
download (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 .git-ftp-ignore file.
pull (EXPERIMENTAL)
Downloads changes from the remote host into a separate commit and merges that into
your current branch. If you just want to download the files without a merge,
consider download. This feature needs lftp to be installed.
snapshot (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.
show Downloads last uploaded SHA1 from log and hooks `git show`.
log Downloads last uploaded SHA1 from log and hooks `git log`.
add-scope <scope>
Creates a new scope (e.g. dev, production, testing, foobar). This is a wrapper
action over git-config. See SCOPES section for more information.
remove-scope <scope>
Remove a scope.
help Shows a help screen.
OPTIONS
-u [username], --user [username]
FTP login name. If no argument is given, local user will be taken.
-p [password], --passwd [password]
FTP password. See -P for interactive password prompt. (note)
-P, --ask-passwd
Ask for FTP password interactively.
-k [[account]@[host]], --keychain [[account]@[host]]
FTP password from KeyChain (macOS only).
-a, --all
Uploads all files of current Git checkout.
-c, --commit
Sets SHA1 hash of last deployed commit by option.
-A, --active
Uses FTP active mode. This works only if you have either no firewall and a direct
connection to the server or an FTP aware firewall. If you don’t know what it
means, you probably won’t need it.
-b [branch], --branch [branch]
Push a specific branch
-s [scope], --scope [scope]
Using a scope (e.g. dev, production, testing, foobar). See SCOPE and DEFAULTS
section for more information.
-l, --lock
Enable remote locking.
-D, --dry-run
Does not upload or delete anything, but tries to get the .git-ftp.log file from
remote host.
-f, --force
Does not ask any questions, it just does.
-n, --silent
Be silent.
-h, --help
Prints some usage information.
-v, --verbose
Be verbose.
-vv Be as verbose as possible. Useful for debug information.
--remote-root
Specifies the remote root directory to deploy to. The remote path in the URL is
ignored.
--syncroot
Specifies a local directory to sync from as if it were the git project root path.
--key SSH private key file name for SFTP.
--pubkey
SSH public key file name. Used with –key option.
--insecure
Don’t verify server’s certificate.
--cacert <file>
Use as CA certificate store. Useful when a server has a self-signed certificate.
--disable-epsv
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.
--no-commit
Stop while merging downloaded changes during the pull action. A commit is made
anyway, but the merge is interrupted. If you just want to download the files you
could also consider the action download.
--changed-only
During the ftp mirror operation during a pull command, consider only the files
changed since the deployed commit.
--no-verify
Bypass the pre-ftp-push hook. See HOOKS section.
--enable-post-errors
Fails if post-ftp-push raises an error.
--auto-init
Automatically run init action when running push action
--version
Prints version.
-x [protocol://]host[:port], --proxy [protocol://]host[:port]
Use the specified proxy. This option is passed to curl. See the curl manual for
more information.
URL
The scheme of an URL is what you would expect
protocol://host.domain.tld:port/path
Below a full featured URL to host.example.com on port 2121 to path mypath using protocol
ftp:
ftp://host.example.com:2121/mypath
But, there is not just FTP. Supported protocols are:
ftp://...
FTP (default if no protocol is set)
sftp://...
SFTP
ftps://...
FTPS
ftpes://...
FTP over explicit SSL (FTPES) protocol
EXAMPLES
FIRST UPLOADS
Upload your files to an FTP server the first time:
$ git ftp init -u "john" -P "ftp://example.com/public_html"
It will authenticate with the username john and ask for the password. By default, it
tries to transfer data in EPSV mode. Depending on the network and server configuration,
that may fail. You can try to add the --disable-epsv option to use the IPv4 passive FTP
connection (PASV). In rare circumstances, you can use --active for the original FTP
transfer mode. These options do not apply to SFTP.
You are less likely to face connection problems with SFTP. But be aware of the different
handling of relative and absolute paths. If the directory public_html is in the home
directory on the server, then upload like this:
$ git ftp init -u "john" --key "$HOME/.ssh/id_rsa" "sftp://example.com/~/public_html"
Otherwise it will use an absolute path, for example:
$ git ftp init -u "john" --key "$HOME/.ssh/id_rsa" "sftp://example.com/var/www"
On some systems Git-ftp fails to verify the server’s fingerprint. You can then use the
--insecure option to skip the verification. That will leave you vulnerable to
man-in-the-middle attacks, but is still more secure than plain FTP.
Git-ftp guesses the path of the public key file corresponding to your private key file.
If you just have a private key, for example a .pem file, you need Git-ftp version 1.3.4
and Curl version 7.39.0 or newer. If you have an older version of Git-ftp or Curl, you
can create the public key with the ssh-keygen command:
$ ssh-keygen -y -f key.pem > key.pem.pub
RESET THE UPLOADED STATE
Many people already uploaded their files to the server. If you want to mark the uploaded
version as the same as your local branch:
$ git ftp catchup
This example omits options like --user, --password and url. See DEFAULTS below to learn
how to store your configuration so that you don’t need to repeat it.
After you stored the commit id of the uploaded commit via init or catchup, you can then
upload any new commits:
$ git ftp push
If you discovered a bug in the last uploaded version and you want to go back by three
commits:
$ git checkout HEAD~3
$ git ftp push
Or maybe some files got changed on the server and you want to upload all changes between
branch master and branch develop:
$ git checkout develop # This is the version which is uploaded.
$ git ftp push --commit master # Upload changes compared to master.
DEFAULTS
Don’t repeat yourself. Setting config defaults for git-ftp in .git/config
$ git config git-ftp.<(url|user|password|syncroot|cacert|keychain|...)> <value>
Everyone likes examples:
$ 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
$ git config git-ftp.remote-root htdocs
$ git config git-ftp.disable-epsv 1
$ git config git-ftp.no-commit 1
After setting those defaults, push to john@ftp.example.com is as simple as
$ git ftp push
If you run into issues with setting up your password please check this note.
SCOPES
Need different config defaults per each system or environment? Use the so called scope
feature.
Useful if you use multi environment development. Like a development, testing and a
production environment.
$ git config git-ftp.<scope>.<(url|user|password|syncroot|cacert)> <value>
So in the case below you would set a testing scope and a production scope.
Here we set the params for the scope “testing”
$ git config git-ftp.testing.url ftp.testing.com:8080/foobar-path
$ git config git-ftp.testing.password simp3l
Here we set the params for the scope “production”
$ git config git-ftp.production.user manager
$ git config git-ftp.production.url live.example.com
$ git config git-ftp.production.password n0tThatSimp3l
Pushing to scope testing alias john@ftp.testing.com:8080/foobar-path using password simp3l
$ git ftp push -s testing
Note: The SCOPE feature can be mixed with the DEFAULTS feature. Because we didn’t set the
user for this scope, git-ftp uses john as user as set before in DEFAULTS.
Pushing to scope production alias manager@live.example.com using password n0tThatSimp3l
$ git ftp push -s production
Hint: If your scope name is identical with your branch name. You can skip the scope
argument, e.g. if your current branch is “production”:
$ git ftp push -s
You can also create scopes using the add-scope action. All settings can be defined in the
URL. Here we create the production scope using add-scope
$ git ftp add-scope production ftp://manager:n0tThatSimp3l@live.example.com/foobar-path
Deleting scopes is easy using the remove-scope action.
$ git ftp remove-scope production
IGNORING FILES TO BE SYNCED
Add patterns to .git-ftp-ignore and all matching file names will be ignored. The patterns
are interpreted as shell glob patterns since version 1.1.0. Before version 1.1.0,
patterns were interpreted as regular expressions. Here are some glob pattern examples:
Ignoring everything in a directory named config:
config/*
Ignoring all files having extension .txt:
*.txt
Ignoring a single file called foobar.txt:
foobar.txt
Ignoring Git related files:
.gitignore
*/.gitignore # ignore files in sub directories
*/.gitkeep
.git-ftp-ignore
.git-ftp-include
.gitlab-ci.yml
SYNCING UNTRACKED FILES
The .git-ftp-include 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’s name. For example, if you have a file called VERSION.txt then add
the following line:
!VERSION.txt
If you have a file that should be uploaded whenever a tracked file changes, add a line
beginning with the untracked file’s name followed by a colon and the tracked file’s name.
For example, if you have a CSS file compiled from an SCSS file then add the following
line:
css/style.css:scss/style.scss
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.
css/style.css:scss/style.scss
css/style.css:scss/mixins.scss
If a local untracked file is deleted, any change of a paired tracked file will trigger the
deletion of the remote file on the server.
All paths are usually relative to the Git working directory. When using the --syncroot
option, paths of tracked files (right side of the colon) are relative to the set syncroot.
Example:
# upload "html/style.css" triggered by html/style.scss
# with syncroot "html"
html/style.css:style.scss
If your source file is outside the syncroot, prefix it with a / and define a path relative
to the Git working directory. For example:
# upload "dist/style.css" with syncroot "dist"
dist/style.css:/src/style.scss
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:
vendor/:composer.lock
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.
DOWNLOADING FILES (EXPERIMENTAL)
WARNING: It can delete local untracked files that are not listed in your .git-ftp-ignore
file.
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.
git ftp download
It uses lftp’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
git ftp pull
It does the following steps for you:
git checkout <remote-commit>
git ftp download
git add --all
git commit -m '[git-ftp] remotely untracked modifications'
git ftp catchup
git checkout <my-branch>
git merge <new-remote-commit>
If you want to inspect the downloaded changes before merging them into your current
branch, add the option --no-commit. 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.
git ftp pull --no-commit
# inspect the result and commit them
git commit
# or abort the merge
git merge --abort
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.
HOOKS (EXPERIMENTAL)
This feature is experimental. The interface may change.
Git-ftp supports client-side hook scripts during the init and the push action.
pre-ftp-push 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.
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.
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’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 .git-ftp-include
file and the .git-ftp-ignore file.
Exiting with non-zero status from this script causes Git-ftp to abort and exit with status
9.
An example script is:
#!/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:
#
# <status> <path>
#
# 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 '' status file
do
if [ "$status" = "A" ]
then
if grep 'TODO' "$file"; then
echo "TODO found in file $file, not uploading."
exit 1
fi
fi
done
exit 0
post-ftp-push is called after the transfer has been finished. The standard input is
empty, but the parameters are the same as given to the pre-ftp-push hook. This hook is
not bypassed by the –no-verify option. It is meant primarily for notification and its
exit status does not have any effect.
PASSWORDS
If your password contains special characters you have to take it with care. In most cases
it is a good idea to quote passwords with single quotes:
--passwd '#my$fancy!secret'
Mostly --ask-passwd works even if --passwd does not work. So maybe you can give this a
try.
If your password starts with a hyphen/dash (-) even quoting might fail. This is by design
(https://github.com/git-ftp/git-ftp/issues/468) and will not be fixed. In this case you
can use one of the other options to set your password: the defaults feature using git
config, --ask-passwd or ~/.netrc.
Quoting also works if a default is set with git config:
$ git config git-ftp.password '#my$fancy!secret'
NETRC
In the backend, Git-ftp uses curl. This means ~/.netrc could be used beside the other
options of Git-ftp to authenticate.
$ editor ~/.netrc
machine ftp.example.com
login john
password SECRET
With git-ftp the credentials stored in this file are used if no username is set. For
example, if you set up your .netrc file like this you can just call
git ftp init ftp.example.com
Of course this can be combined with the defaults feature to set config defaults for other
options as well.
Keychain on macOS
On macOS you can use the built in keychain to store and get your passwords.
You can use this feature by using the option --keychain in your command:
$ git ftp init --keychain account@host ftpes://host
You can omit the value for this option. Then git-ftp will guess the account and hostname
from user and url.
Or you can set a config for this, so you don’t need to repeat yourself (see defaults for
details):
$ git config git-ftp.keychain account@host
You can omit the hostname here. If there is no @ in the config value git-ftp will guess
the hostname from url.
If you run a command using the keychain feature, the system might ask you if git-ftp is
allowed to access the keychain entry. If the keychain is locked you have to enter the
keychain password (not the value of the entry), sometimes twice.
If your password is not in your keychain yet it is recommended adding it using the
following command:
$ security add-internet-password -a account -r "ftp " -s host -w secr3t
The options are: - -a: user account - -r: protocol; has to be exactly 4 characters long,
so if you use FTP it should be "ftp ", for FTPS and FTPES use ftps and for SSH with
password auth you can use "ftp " as well. - -s: your host name; includes subdomains but
no paths - -w: password
You can omit the option -r and everything will work fine, but the Keychain Access Utility
will not show the server in the field “Where:”. This is only shown if -r and -s are set
both.
If you create a keychain entry with the Keychain Access Utility it creates a generic
password and not an internet password. Therefore, unfortunately, this will not work.
Please not that the keychain entry can not be used for password protected private keys in
SSH.
EXIT CODES
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:
1 Unknown error
2 Wrong Usage
3 Missing arguments
4 Error while uploading
5 Error while downloading
6 Unknown protocol
7 Remote locked
8 Not a Git project
9 The pre-ftp-push hook failed
10 A local file operation like cd or mkdir failed
KNOWN ISSUES & BUGS
The upstream BTS can be found at <https://github.com/git-ftp/git-ftp/issues>.
AUTHORS
Git-ftp was started by Rene Moser and is currently maintained by Maikel Linke. Numerous
contributions have come from GitHub users. See the AUTHORS file for an incomplete list of
contributors.