1GIT-FTP(1) GIT-FTP(1)
2 This is the manual for version 1.6.0-UNRELEASED. Please consider the
6 changelog or select your version from the Branch > Tags select above to
7 see the manual for another version.
8
10 Git-ftp - Git powered FTP client written as shell script.
11
13 git-ftp <action> [<options>] [<url>]
14
16 Git-ftp is an FTP client using Git (http://git-scm.org) to determine
17 which local files to upload or which files to delete on the remote
18 host.
19 It saves the deployed state by uploading the SHA1 hash in the .git-
21 ftp.log file. There is no need for Git to be installed on the remote
22 host.
23 Even if you play with different branches, git-ftp knows which files are
25 different and handles only those files. That saves time and bandwidth.
26
28 init Uploads all git-tracked non-ignored files to the remote server
29 and creates the .git-ftp.log file containing the SHA1 of the
30 latest commit.
31 catchup
33 Creates or updates the .git-ftp.log file on the remote host. It
34 assumes that you uploaded all other files already. You might
35 have done that with another program.
36 push Uploads files that have changed and deletes files that have been
38 deleted since the last upload. If you are using GIT LFS, this
39 uploads LFS link files, not large files (stored on LFS server).
40 To upload the LFS tracked files, run git lfs pull before git ftp
41 push: LFS link files will be replaced with large files so they
42 can be uploaded.
43 download (EXPERIMENTAL)
45 Downloads changes from the remote host into your working tree.
46 This feature needs lftp to be installed and does not use any
47 power of Git. WARNING: It can delete local untracked files that
48 are not listed in your .git-ftp-ignore file.
49 pull (EXPERIMENTAL)
51 Downloads changes from the remote host into a separate commit
52 and merges that into your current branch. If you just want to
53 download the files without a merge, consider download. This
54 feature needs lftp to be installed.
55 snapshot (EXPERIMENTAL)
57 Downloads files into a new Git repository. Takes an additional
58 argument as local destination directory. Example: `git-ftp
59 snapshot ftp://example.com/public_html projects/example` This
60 feature needs lftp to be installed.
61 show Downloads last uploaded SHA1 from log and hooks `git show`.
63 log Downloads last uploaded SHA1 from log and hooks `git log`.
65 add-scope <scope>
67 Creates a new scope (e.g. dev, production, testing, foobar).
68 This is a wrapper action over git-config. See SCOPES section
69 for more information.
70 remove-scope <scope>
72 Remove a scope.
73 help Shows a help screen.
75
77 -u [username], --user [username]
78 FTP login name. If no argument is given, local user will be
79 taken.
80 -p [password], --passwd [password]
82 FTP password. See -P for interactive password prompt. (note)
83 -P, --ask-passwd
85 Ask for FTP password interactively.
86 -k [[account]@[host]], --keychain [[account]@[host]]
88 FTP password from KeyChain (macOS only).
89 -a, --all
91 Uploads all files of current Git checkout.
92 -c, --commit
94 Sets SHA1 hash of last deployed commit by option.
95 -A, --active
97 Uses FTP active mode. This works only if you have either no
98 firewall and a direct connection to the server or an FTP aware
99 firewall. If you don’t know what it means, you probably won’t
100 need it.
101 -b [branch], --branch [branch]
103 Push a specific branch
104 -s [scope], --scope [scope]
106 Using a scope (e.g. dev, production, testing, foobar). See
107 SCOPE and DEFAULTS section for more information.
108 -l, --lock
110 Enable remote locking.
111 -D, --dry-run
113 Does not upload or delete anything, but tries to get the .git-
114 ftp.log file from remote host.
115 -f, --force
117 Does not ask any questions, it just does.
118 -n, --silent
120 Be silent.
121 -h, --help
123 Prints some usage information.
124 -v, --verbose
126 Be verbose.
127 -vv Be as verbose as possible. Useful for debug information.
129 --remote-root
131 Specifies the remote root directory to deploy to. The remote
132 path in the URL is ignored.
133 --syncroot
135 Specifies a local directory to sync from as if it were the git
136 project root path.
137 --key SSH private key file name for SFTP.
139 --pubkey
141 SSH public key file name. Used with –key option.
142 --insecure
144 Don’t verify server’s certificate.
145 --cacert <file>
147 Use as CA certificate store. Useful when a server has a self-
148 signed certificate.
149 --disable-epsv
151 Tell curl to disable the use of the EPSV command when doing pas‐
152 sive FTP transfers. Curl will normally always first attempt to
153 use EPSV before PASV, but with this option, it will not try us‐
154 ing EPSV.
155 --no-commit
157 Stop while merging downloaded changes during the pull action. A
158 commit is made anyway, but the merge is interrupted. If you
159 just want to download the files you could also consider the ac‐
160 tion download.
161 --changed-only
163 During the ftp mirror operation during a pull command, consider
164 only the files changed since the deployed commit.
165 --no-verify
167 Bypass the pre-ftp-push hook. See HOOKS section.
168 --enable-post-errors
170 Fails if post-ftp-push raises an error.
171 --auto-init
173 Automatically run init action when running push action
174 --version
176 Prints version.
177 -x [protocol://]host[:port], --proxy [protocol://]host[:port]
179 Use the specified proxy. This option is passed to curl. See
180 the curl manual for more information.
181
183 The scheme of an URL is what you would expect
184 protocol://host.domain.tld:port/path
186 Below a full featured URL to host.example.com on port 2121 to path my‐
188 path using protocol ftp:
189 ftp://host.example.com:2121/mypath
191 But, there is not just FTP. Supported protocols are:
193 ftp://...
195 FTP (default if no protocol is set)
196 sftp://...
198 SFTP
199 ftps://...
201 FTPS
202 ftpes://...
204 FTP over explicit SSL (FTPES) protocol
205
207 FIRST UPLOADS
208 Upload your files to an FTP server the first time:
209 $ git ftp init -u "john" -P "ftp://example.com/public_html"
211 It will authenticate with the username john and ask for the password.
213 By default, it tries to transfer data in EPSV mode. Depending on the
214 network and server configuration, that may fail. You can try to add
215 the --disable-epsv option to use the IPv4 passive FTP connection
216 (PASV). In rare circumstances, you can use --active for the original
217 FTP transfer mode. These options do not apply to SFTP.
218 You are less likely to face connection problems with SFTP. But be
220 aware of the different handling of relative and absolute paths. If the
221 directory public_html is in the home directory on the server, then up‐
222 load like this:
223 $ git ftp init -u "john" --key "$HOME/.ssh/id_rsa" "sftp://example.com/~/public_html"
225 Otherwise it will use an absolute path, for example:
227 $ git ftp init -u "john" --key "$HOME/.ssh/id_rsa" "sftp://example.com/var/www"
229 On some systems Git-ftp fails to verify the server’s fingerprint. You
231 can then use the --insecure option to skip the verification. That will
232 leave you vulnerable to man-in-the-middle attacks, but is still more
233 secure than plain FTP.
234 Git-ftp guesses the path of the public key file corresponding to your
236 private key file. If you just have a private key, for example a .pem
237 file, you need Git-ftp version 1.3.4 and Curl version 7.39.0 or newer.
238 If you have an older version of Git-ftp or Curl, you can create the
239 public key with the ssh-keygen command:
240 $ ssh-keygen -y -f key.pem > key.pem.pub
242 RESET THE UPLOADED STATE
244 Many people already uploaded their files to the server. If you want to
245 mark the uploaded version as the same as your local branch:
246 $ git ftp catchup
248 This example omits options like --user, --password and url. See DE‐
250 FAULTS below to learn how to store your configuration so that you don’t
251 need to repeat it.
252 After you stored the commit id of the uploaded commit via init or
254 catchup, you can then upload any new commits:
255 $ git ftp push
257 If you discovered a bug in the last uploaded version and you want to go
259 back by three commits:
260 $ git checkout HEAD~3
262 $ git ftp push
263 Or maybe some files got changed on the server and you want to upload
265 all changes between branch master and branch develop:
266 $ git checkout develop # This is the version which is uploaded.
268 $ git ftp push --commit master # Upload changes compared to master.
269
271 Don’t repeat yourself. Setting config defaults for git-ftp in
272 .git/config
273 $ git config git-ftp.<(url|user|password|syncroot|cacert|keychain|...)> <value>
275 Everyone likes examples:
277 $ git config git-ftp.user john
279 $ git config git-ftp.url ftp.example.com
280 $ git config git-ftp.password secr3t
281 $ git config git-ftp.syncroot path/dir
282 $ git config git-ftp.cacert caCertStore
283 $ git config git-ftp.deployedsha1file mySHA1File
284 $ git config git-ftp.insecure 1
285 $ git config git-ftp.key ~/.ssh/id_rsa
286 $ git config git-ftp.keychain user@example.com
287 $ git config git-ftp.remote-root htdocs
288 $ git config git-ftp.disable-epsv 1
289 $ git config git-ftp.no-commit 1
290 After setting those defaults, push to john@ftp.example.com is as simple
292 as
293 $ git ftp push
295 If you run into issues with setting up your password please check this
297 note.
298
300 Need different config defaults per each system or environment? Use the
301 so called scope feature.
302 Useful if you use multi environment development. Like a development,
304 testing and a production environment.
305 $ git config git-ftp.<scope>.<(url|user|password|syncroot|cacert)> <value>
307 So in the case below you would set a testing scope and a production
309 scope.
310 Here we set the params for the scope “testing”
312 $ git config git-ftp.testing.url ftp.testing.com:8080/foobar-path
314 $ git config git-ftp.testing.password simp3l
315 Here we set the params for the scope “production”
317 $ git config git-ftp.production.user manager
319 $ git config git-ftp.production.url live.example.com
320 $ git config git-ftp.production.password n0tThatSimp3l
321 Pushing to scope testing alias john@ftp.testing.com:8080/foobar-path
323 using password simp3l
324 $ git ftp push -s testing
326 Note: The SCOPE feature can be mixed with the DEFAULTS feature. Be‐
328 cause we didn’t set the user for this scope, git-ftp uses john as user
329 as set before in DEFAULTS.
330 Pushing to scope production alias manager@live.example.com using pass‐
332 word n0tThatSimp3l
333 $ git ftp push -s production
335 Hint: If your scope name is identical with your branch name. You can
337 skip the scope argument, e.g. if your current branch is “production”:
338 $ git ftp push -s
340 You can also create scopes using the add-scope action. All settings
342 can be defined in the URL. Here we create the production scope using
343 add-scope
344 $ git ftp add-scope production ftp://manager:n0tThatSimp3l@live.example.com/foobar-path
346 Deleting scopes is easy using the remove-scope action.
348 $ git ftp remove-scope production
350
352 Add patterns to .git-ftp-ignore and all matching file names will be ig‐
353 nored. The patterns are interpreted as shell glob patterns since ver‐
354 sion 1.1.0. Before version 1.1.0, patterns were interpreted as regular
355 expressions. Here are some glob pattern examples:
356 Ignoring everything in a directory named config:
358 config/*
360 Ignoring all files having extension .txt:
362 *.txt
364 Ignoring a single file called foobar.txt:
366 foobar.txt
368 Ignoring Git related files:
370 .gitignore
372 */.gitignore # ignore files in sub directories
373 */.gitkeep
374 .git-ftp-ignore
375 .git-ftp-include
376 .gitlab-ci.yml
377
379 The .git-ftp-include file specifies intentionally untracked files that
380 Git-ftp should upload. If you have a file that should always be up‐
381 loaded, add a line beginning with ! followed by the file’s name. For
382 example, if you have a file called VERSION.txt then add the following
383 line:
384 !VERSION.txt
386 If you have a file that should be uploaded whenever a tracked file
388 changes, add a line beginning with the untracked file’s name followed
389 by a colon and the tracked file’s name. For example, if you have a CSS
390 file compiled from an SCSS file then add the following line:
391 css/style.css:scss/style.scss
393 If you have multiple source files, you can add multiple lines for each
395 of them. Whenever one of the tracked files changes, the upload of the
396 paired untracked file will be triggered.
397 css/style.css:scss/style.scss
399 css/style.css:scss/mixins.scss
400 If a local untracked file is deleted, any change of a paired tracked
402 file will trigger the deletion of the remote file on the server.
403 All paths are usually relative to the Git working directory. When us‐
405 ing the --syncroot option, paths of tracked files (right side of the
406 colon) are relative to the set syncroot. Example:
407 # upload "html/style.css" triggered by html/style.scss
409 # with syncroot "html"
410 html/style.css:style.scss
411 If your source file is outside the syncroot, prefix it with a / and de‐
413 fine a path relative to the Git working directory. For example:
414 # upload "dist/style.css" with syncroot "dist"
416 dist/style.css:/src/style.scss
417 It is also possible to upload whole directories. For example, if you
419 use a package manager like composer, you can upload all vendor packages
420 when the file composer.lock changes:
421 vendor/:composer.lock
423 But keep in mind that this will upload all files in the vendor folder,
425 even those that are on the server already. And it will not delete
426 files from that directory if local files are deleted.
427
429 WARNING: It can delete local untracked files that are not listed in
430 your .git-ftp-ignore file.
431 You can use git-ftp to download from the remote host into your reposi‐
433 tory. You will need to install the lftp command line tool for that.
434 git ftp download
436 It uses lftp’s mirror command to download all files that are different
438 on the remote host. You can inspect the changes with git-diff. But if
439 you have some local commits that have not been uploaded to the remote
440 host, you may not compare to the right version. You need to compare
441 the downloaded files to the commit that was uploaded last. This magic
442 is done automatically by
443 git ftp pull
445 It does the following steps for you:
447 git checkout <remote-commit>
449 git ftp download
450 git add --all
451 git commit -m '[git-ftp] remotely untracked modifications'
452 git ftp catchup
453 git checkout <my-branch>
454 git merge <new-remote-commit>
455 If you want to inspect the downloaded changes before merging them into
457 your current branch, add the option --no-commit. It will stop during
458 the merge at the end of the pull action. You can inspect the merge re‐
459 sult first and can then decide to continue or abort.
460 git ftp pull --no-commit
462 # inspect the result and commit them
463 git commit
464 # or abort the merge
465 git merge --abort
466 If you abort the merge, the downloaded changes will stay in an unrefer‐
468 enced commit until the Git garbage collector is run. The commit id
469 will be printed so that you can tag it or create a new branch.
470
472 This feature is experimental. The interface may change.
473 Git-ftp supports client-side hook scripts during the init and the push
475 action.
476 pre-ftp-push is called just before the upload to the server starts, but
478 after the changeset of files was generated. It can be bypassed with
479 the –no-verify option.
480 The hook is called with four parameters. The first is the used scope
482 or the host name if no scope is used. The second parameter is the des‐
483 tination URL. The third is the local commit id which is going to be
484 uploaded and the fourth is the remote commit id on the server which is
485 going to be updated.
486 The standard input is a list of all filenames to sync. Each file is
488 preceeded by A or D followed by a space. A means that this file is
489 scheduled for upload, D means it’s scheduled for deletion. All entries
490 are separated by the NUL byte. This list is different to git diff, be‐
491 cause it has been changed by the rules of the .git-ftp-include file and
492 the .git-ftp-ignore file.
493 Exiting with non-zero status from this script causes Git-ftp to abort
495 and exit with status 9.
496 An example script is:
498 #!/bin/bash
500 #
501 # An example hook script to verify what is about to be uploaded.
502 #
503 # Called by "git ftp push" after it has checked the remote status, but before
504 # anything has been pushed. If this script exits with a non-zero status nothing
505 # will be pushed.
506 #
507 # This hook is called with the following parameters:
508 #
509 # $1 -- Scope name if set or host name of the remote
510 # $2 -- URL to which the upload is being done
511 # $3 -- Local commit id which is being uploaded
512 # $4 -- Remote commit id which is on the server
513 #
514 # Information about the files which are being uploaded or deleted is supplied
515 # as NUL separated entries to the standard input in the form:
516 #
517 # <status> <path>
518 #
519 # The status is either A for upload or D for delete. The path contains the
520 # path to the local file. It contains the syncroot if set.
521 #
522 # This sample shows how to prevent upload of files containing the word TODO.
523 remote="$1"
525 url="$2"
526 local_sha="$3"
527 remote_sha="$4"
528 while read -r -d '' status file
530 do
531 if [ "$status" = "A" ]
532 then
533 if grep 'TODO' "$file"; then
534 echo "TODO found in file $file, not uploading."
535 exit 1
536 fi
537 fi
538 done
539 exit 0
541 post-ftp-push is called after the transfer has been finished. The
543 standard input is empty, but the parameters are the same as given to
544 the pre-ftp-push hook. This hook is not bypassed by the –no-verify op‐
545 tion. It is meant primarily for notification and its exit status does
546 not have any effect.
547
549 If your password contains special characters you have to take it with
550 care. In most cases it is a good idea to quote passwords with single
551 quotes:
552 --passwd '#my$fancy!secret'
554 Mostly --ask-passwd works even if --passwd does not work. So maybe you
556 can give this a try.
557 If your password starts with a hyphen/dash (-) even quoting might fail.
559 This is by design (https://github.com/git-ftp/git-ftp/issues/468) and
560 will not be fixed. In this case you can use one of the other options
561 to set your password: the defaults feature using git config, --ask-
562 passwd or ~/.netrc.
563 Quoting also works if a default is set with git config:
565 $ git config git-ftp.password '#my$fancy!secret'
567 NETRC
569 In the backend, Git-ftp uses curl. This means ~/.netrc could be used
570 beside the other options of Git-ftp to authenticate.
571 $ editor ~/.netrc
573 machine ftp.example.com
574 login john
575 password SECRET
576 With git-ftp the credentials stored in this file are used if no user‐
578 name is set. For example, if you set up your .netrc file like this you
579 can just call
580 git ftp init ftp.example.com
582 Of course this can be combined with the defaults feature to set config
584 defaults for other options as well.
585 Keychain on macOS
587 On macOS you can use the built in keychain to store and get your pass‐
588 words.
589 You can use this feature by using the option --keychain in your com‐
591 mand:
592 $ git ftp init --keychain account@host ftpes://host
594 You can omit the value for this option. Then git-ftp will guess the
596 account and hostname from user and url.
597 Or you can set a config for this, so you don’t need to repeat yourself
599 (see defaults for details):
600 $ git config git-ftp.keychain account@host
602 You can omit the hostname here. If there is no @ in the config value
604 git-ftp will guess the hostname from url.
605 If you run a command using the keychain feature, the system might ask
607 you if git-ftp is allowed to access the keychain entry. If the key‐
608 chain is locked you have to enter the keychain password (not the value
609 of the entry), sometimes twice.
610 If your password is not in your keychain yet it is recommended adding
612 it using the following command:
613 $ security add-internet-password -a account -r "ftp " -s host -w secr3t
615 The options are: - -a: user account - -r: protocol; has to be exactly 4
617 characters long, so if you use FTP it should be "ftp ", for FTPS and
618 FTPES use ftps and for SSH with password auth you can use "ftp " as
619 well. - -s: your host name; includes subdomains but no paths - -w:
620 password
621 You can omit the option -r and everything will work fine, but the Key‐
623 chain Access Utility will not show the server in the field “Where:”.
624 This is only shown if -r and -s are set both.
625 If you create a keychain entry with the Keychain Access Utility it cre‐
626 ates a generic password and not an internet password. Therefore, un‐
627 fortunately, this will not work.
628 Please not that the keychain entry can not be used for password pro‐
630 tected private keys in SSH.
631
633 There are a bunch of different error codes and their corresponding er‐
634 ror messages that may appear during bad conditions. At the time of
635 this writing, the exit codes are:
636 1 Unknown error
638 2 Wrong Usage
640 3 Missing arguments
642 4 Error while uploading
644 5 Error while downloading
646 6 Unknown protocol
648 7 Remote locked
650 8 Not a Git project
652 9 The pre-ftp-push hook failed
654 10 A local file operation like cd or mkdir failed
656
658 The upstream BTS can be found at <https://github.com/git-ftp/git-
659 ftp/issues>.
660
662 Git-ftp was started by Rene Moser and is currently maintained by Maikel
663 Linke. Numerous contributions have come from GitHub users. See the
664 AUTHORS file for an incomplete list of contributors.
665Git-ftp 1.6.0 2020-02-03 GIT-FTP(1)