GIT-FTP(1)

📦
version 1.6.0 · 4 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 GIT-FTP(1) 💖

okay bestie, this is the manual for version 1.6.0-UNRELEASED. lowkey if you want a different version, go peek at the changelog (../CHANGELOG.md) or hit up Branch > Tags above to grab the manual for whichever version you're on. ✨

🌸 NAME 🌸

Git-ftp — a Git-powered FTP client that's literally just a shell script. no cap. 👑

🦋 SYNOPSIS 🦋

git-ftp <action> [<options>] [<url>]

💅 DESCRIPTION 💅

Git-ftp is an FTP client that uses Git (http://git-scm.org) to figure out which local files need uploading and which files on the remote host need to go bye-bye. 🗑️

It keeps track of the deployed state by uploading the SHA1 hash into the .git-ftp.log file. And the best part? You do not need Git installed on the remote host. not even a little bit. 🌈

And even if you're out here playing with different branches, git-ftp knows which files are different and only touches those ones. which means it saves you time AND bandwidth. iconic behavior, honestly. ⏱️💸

✨ ACTIONS ✨

  • init — uploads every git-tracked non-ignored file to the remote server, then creates the .git-ftp.log file containing the SHA1 of the latest commit. the classic first-move. 🎀
  • catchup — creates or updates the .git-ftp.log file on the remote host. It just assumes you already uploaded all the other files yourself. Maybe you did that with some other program, who's to say. 🤷‍♀️
  • push — uploads the files that changed and deletes the files that got deleted since the last upload. And if you're using GIT LFS? this uploads the LFS link files, not the big files (those live on the LFS server). To actually get the LFS-tracked files up there, run git lfs pull before git ftp push — that swaps the LFS link files out for the real large files so they can be uploaded. 🔥
  • download (EXPERIMENTAL) — downloads changes from the remote host straight into your working tree. This one needs lftp installed and uses absolutely zero Git power. > ⚠️ WARNING: it can delete local untracked files that aren't listed in your .git-ftp-ignore file. be careful bestie, fr fr. 💀
  • pull (EXPERIMENTAL) — downloads changes from the remote host into a separate commit and merges that into your current branch. If you just want the files downloaded with no merge drama, go look at download instead. This one also needs lftp installed. 🌸
  • snapshot (EXPERIMENTAL) — downloads files into a brand new Git repository. Takes an extra argument as the local destination directory. Example: git-ftp snapshot ftp://example.com/public_html projects/example This one needs lftp installed too. 🦋
  • show — downloads the last uploaded SHA1 from the log and hooks git show.
  • log — downloads the last uploaded SHA1 from the log and hooks git log.
  • add-scope <scope> — creates a new scope (like dev, production, testing, foobar). It's just a wrapper action over git-config. Peep the SCOPES section for more info. 👀
  • remove-scope <scope> — removes a scope. poof, gone. 🫧
  • help — shows a help screen. we love a little help. 🫶

🎀 OPTIONS 🎀

  • -u [username], --user [username] — FTP login name. If you don't give an argument, the local user gets taken instead. 🙈
  • -p [password], --passwd [password] — FTP password. See -P for the interactive password prompt. (note)
  • -P, --ask-passwd — ask for the FTP password interactively. much safer vibe. 💅
  • -k [[account]@[host]], --keychain [[account]@[host]] — grab the FTP password from KeyChain. (macOS only, sorry bestie.) 🍓
  • -a, --all — uploads all files of the current Git checkout. everything. the whole thing.
  • -c, --commit — sets the SHA1 hash of the last deployed commit via this option.
  • -A, --active — uses FTP active mode. This only works if you've either got no firewall and a direct connection to the server, or an FTP-aware firewall. If you don't know what that means, you probably won't need it. ngl that's most of us. 🙈
  • -b [branch], --branch [branch] — push a specific branch. 🌿
  • -s [scope], --scope [scope] — use a scope (like dev, production, testing, foobar). Check the SCOPE and DEFAULTS sections for more info. 👑
  • -l, --lock — enable remote locking. 🔒
  • -D, --dry-run — doesn't upload or delete anything, but it does try to fetch the .git-ftp.log file from the remote host. a little peek, no commitment. 👀
  • -f, --force — doesn't ask any questions. It just does it. no thoughts, head empty, sending it. 💥
  • -n, --silent — be silent. 🤫
  • -h, --help — prints some usage information.
  • -v, --verbose — be verbose. 🗣️
  • -vv — be as verbose as possible. Useful for debug information. maximum yapping mode. 📢
  • --remote-root — specifies the remote root directory to deploy to. The remote path inside the URL gets 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 the --key option.
  • --insecure — don't verify the server's certificate. yikes but okay. 😬
  • --cacert <file> — use as CA certificate store. Super useful when a server has a self-signed certificate. 🎀
  • --disable-epsv — tells curl to disable the use of the EPSV command when doing passive FTP transfers. Curl will normally always try EPSV first before PASV, but with this option it won't even attempt EPSV. so it goes straight to PASV. periodt.
  • --no-commit — stop while merging downloaded changes during the pull action. A commit is made anyway, but the merge gets interrupted. If you just want to download the files, you could also consider the download action instead. 🛑
  • --changed-only — during the ftp mirror operation during a pull command, only consider the files that changed since the deployed commit. 🦋
  • --no-verify — bypass the pre-ftp-push hook. See the HOOKS section. 🪝
  • --enable-post-errors — fails if post-ftp-push raises an error. 💥
  • --auto-init — automatically run the init action when running the push action. self-care automation. ✨
  • --version — prints version. 🏷️
  • -x [protocol://]host[:port], --proxy [protocol://]host[:port] — use the specified proxy. This option gets 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 bestie, it is not just FTP. The supported protocols are:

  • ftp://... — FTP (this is the 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 adding 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. Oh and heads up — these options do not apply to SFTP. 🙅‍♀️

You're 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 it's 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've got 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 🦋

So 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. Set 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, pushing 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 🎀

okay so bestie, ever wanted different config defaults for each system or environment?? 👀 that's literally what the scope feature is for. it's giving multi-environment dev realness — like a development, a testing AND a production environment, all vibing separately. 💅

$ git config git-ftp.<scope>.<(url|user|password|syncroot|cacert)> <value>

so in the case below you'd set a testing scope and a production scope. slay.

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. no cap.

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. bye bestie 😭

$ 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. (the way that changed… iconic evolution honestly) 🦋

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. 💀 (yes it really said that)

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. 😱 be careful bestie.

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. main character energy tbh.

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. (lowkey a lil side quest for you)

⭐ 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 ✨

okay bestie, passwords are lowkey the drama of the whole git-ftp situation, so listen up 💅

if your password has special characters in it, you gotta treat it gently. most of the time, the move is to wrap that baby in single quotes, like:

--passwd '#my$fancy!secret'

and honestly? --ask-passwd usually works even when --passwd is being a little diva and refuses. so if one isn't giving, try the other, periodt.

🚨 warning bestie 🚨 if your password starts with a hyphen/dash (-), even quoting might not save you. this is by design — [https://github.com/git-ftp/git-ftp/issues/468](https://github.com/git-ftp/git-ftp/issues/468) — and it will not be fixed. like, they said what they said. in that case, 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 🌸

under the hood, git-ftp uses curl. so yes, ~/.netrc can be used alongside all the other git-ftp options to authenticate. it's giving backup plan energy ✨

$ 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. so if you set up your .netrc like that, you can just call:

git ftp init ftp.example.com

and of course, you can combine this with the defaults feature to set config defaults for other options as well. no cap 🧚

🍓 Keychain on macOS 🍓

on macOS you can use the built-in keychain to store and get your passwords. iconic behavior honestly.

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. she's intuitive like that 💅

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. rude but true 😭

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 note 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.

and that's the whole vibe, bestie. this was Git-ftp 1.6.0, dated 2020-02-03, aka GIT-FTP(1) — go forth and sync slayfully 🫶✨💅

📦 where this page comes from