1GIT-FTP(1) GIT-FTP(1)
2
6 Git-ftp - Git powered FTP client written as shell script.
7
9 git-ftp <action> [<options>] [<url>]
10
12 Git-ftp is an FTP client using Git (http://git-scm.org) to determine
13 which local files to upload or which files to delete on the remote
14 host.
15 It saves the deployed state by uploading the SHA1 hash in the
17 .git-ftp.log file. There is no need for Git to be installed on the re‐
18 mote host.
19 Even if you play with different branches, git-ftp knows which files are
21 different and handles only those files. That saves time and bandwidth.
22
24 init Uploads all git-tracked non-ignored files to the remote server
25 and creates the .git-ftp.log file containing the SHA1 of the
26 latest commit.
27 catchup
29 Creates or updates the .git-ftp.log file on the remote host. It
30 assumes that you uploaded all other files already. You might
31 have done that with another program.
32 push Uploads files that have changed and deletes files that have been
34 deleted since the last upload. If you are using GIT LFS, this
35 uploads LFS link files, not large files (stored on LFS server).
36 To upload the LFS tracked files, run git lfs pull before
37 git ftp push: LFS link files will be replaced with large files
38 so they can be uploaded.
39 download (EXPERIMENTAL)
41 Downloads changes from the remote host into your working tree.
42 This feature needs lftp to be installed and does not use any
43 power of Git. WARNING: It can delete local untracked files that
44 are not listed in your .git-ftp-ignore file.
45 pull (EXPERIMENTAL)
47 Downloads changes from the remote host into a separate commit
48 and merges that into your current branch. This feature needs
49 lftp to be installed.
50 snapshot (EXPERIMENTAL)
52 Downloads files into a new Git repository. Takes an additional
53 argument as local destination directory. Example: `git-ftp
54 snapshot ftp://example.com/public_html projects/example` This
55 feature needs lftp to be installed.
56 show Downloads last uploaded SHA1 from log and hooks `git show`.
58 log Downloads last uploaded SHA1 from log and hooks `git log`.
60 add-scope <scope>
62 Creates a new scope (e.g. dev, production, testing, foobar).
63 This is a wrapper action over git-config. See SCOPES section
64 for more information.
65 remove-scope <scope>
67 Remove a scope.
68 help Shows a help screen.
70
72 -u [username], --user [username]
73 FTP login name. If no argument is given, local user will be
74 taken.
75 -p [password], --passwd [password]
77 FTP password. See -P for interactive password prompt.
78 -P, --ask-passwd
80 Ask for FTP password interactively.
81 -k [[user]@[account]], --keychain [[user]@[account]]
83 FTP password from KeyChain (Mac OS X only).
84 -a, --all
86 Uploads all files of current Git checkout.
87 -c, --commit
89 Sets SHA1 hash of last deployed commit by option.
90 -A, --active
92 Uses FTP active mode. This works only if you have either no
93 firewall and a direct connection to the server or an FTP aware
94 firewall. If you don't know what it means, you probably won't
95 need it.
96 -b [branch], --branch [branch]
98 Push a specific branch
99 -s [scope], --scope [scope]
101 Using a scope (e.g. dev, production, testing, foobar). See
102 SCOPE and DEFAULTS section for more information.
103 -l, --lock
105 Enable remote locking.
106 -D, --dry-run
108 Does not upload or delete anything, but tries to get the
109 .git-ftp.log file from remote host.
110 -f, --force
112 Does not ask any questions, it just does.
113 -n, --silent
115 Be silent.
116 -h, --help
118 Prints some usage information.
119 -v, --verbose
121 Be verbose.
122 -vv Be as verbose as possible. Useful for debug information.
124 --remote-root
126 Specifies the remote root directory to deploy to. The remote
127 path in the URL is ignored.
128 --syncroot
130 Specifies a local directory to sync from as if it were the git
131 project root path.
132 --key SSH private key file name for SFTP.
134 --pubkey
136 SSH public key file name. Used with –key option.
137 --insecure
139 Don't verify server's certificate.
140 --cacert <file>
142 Use as CA certificate store. Useful when a server has a
143 self-signed certificate.
144 --disable-epsv
146 Tell curl to disable the use of the EPSV command when doing pas‐
147 sive FTP transfers. Curl will normally always first attempt to
148 use EPSV before PASV, but with this option, it will not try us‐
149 ing EPSV.
150 --no-commit
152 Stop while merging downloaded changes during the pull action.
153 --changed-only
155 During the ftp mirror operation during a pull command, consider
156 only the files changed since the deployed commit.
157 --no-verify
159 Bypass the pre-ftp-push hook. See HOOKS section.
160 --enable-post-errors
162 Fails if post-ftp-push raises an error.
163 --auto-init
165 Automatically run init action when running push action
166 --version
168 Prints version.
169 -x [protocol://]host[:port], --proxy [protocol://]host[:port]
171 Use the specified proxy. This option is passed to curl. See
172 the curl manual for more information.
173
175 The scheme of an URL is what you would expect
176 protocol://host.domain.tld:port/path
178 Below a full featured URL to host.example.com on port 2121 to path my‐
180 path using protocol ftp:
181 ftp://host.example.com:2121/mypath
183 But, there is not just FTP. Supported protocols are:
185 ftp://...
187 FTP (default if no protocol is set)
188 sftp://...
190 SFTP
191 ftps://...
193 FTPS
194 ftpes://...
196 FTP over explicit SSL (FTPES) protocol
197
199 FIRST UPLOADS
200 Upload your files to an FTP server the first time:
201 $ git ftp init -u "john" -P "ftp://example.com/public_html"
203 It will authenticate with the username john and ask for the password.
205 By default, it tries to transfer data in EPSV mode. Depending on the
206 network and server configuration, that may fail. You can try to add
207 the --disable-epsv option to use the IPv4 passive FTP connection
208 (PASV). In rare circumstances, you can use --active for the original
209 FTP transfer mode. These options do not apply to SFTP.
210 You are less likely to face connection problems with SFTP. But be
212 aware of the different handling of relative and absolute paths. If the
213 directory public_html is in the home directory on the server, then up‐
214 load like this:
215 $ git ftp init -u "john" --key "$HOME/.ssh/id_rsa" "sftp://example.com/~/public_html"
217 Otherwise it will use an absolute path, for example:
219 $ git ftp init -u "john" --key "$HOME/.ssh/id_rsa" "sftp://example.com/var/www"
221 On some systems Git-ftp fails to verify the server's fingerprint. You
223 can then use the --insecure option to skip the verification. That will
224 leave you vulnerable to man-in-the-middle attacks, but is still more
225 secure than plain FTP.
226 Git-ftp guesses the path of the public key file corresponding to your
228 private key file. If you just have a private key, for example a .pem
229 file, you need Git-ftp version 1.3.4 and Curl version 7.39.0 or newer.
230 If you have an older version of Git-ftp or Curl, you can create the
231 public key with the ssh-keygen command:
232 $ ssh-keygen -y -f key.pem > key.pem.pub
234 RESET THE UPLOADED STATE
236 Many people already uploaded their files to the server. If you want to
237 mark the uploaded version as the same as your local branch:
238 $ git ftp catchup
240 This example omits options like --user, --password and url. See DE‐
242 FAULTS below to learn how to store your configuration so that you don't
243 need to repeat it.
244 After you stored the commit id of the uploaded commit via init or
246 catchup, you can then upload any new commits:
247 $ git ftp push
249 If you discovered a bug in the last uploaded version and you want to go
251 back by three commits:
252 $ git checkout HEAD~3
254 $ git ftp push
255 Or maybe some files got changed on the server and you want to upload
257 all changes between branch master and branch develop:
258 $ git checkout develop # This is the version which is uploaded.
260 $ git ftp push --commit master # Upload changes compared to master.
261
263 Don't repeat yourself. Setting config defaults for git-ftp in
264 .git/config
265 $ git config git-ftp.<(url|user|password|syncroot|cacert|keychain|...)> <value>
267 Everyone likes examples:
269 $ git config git-ftp.user john
271 $ git config git-ftp.url ftp.example.com
272 $ git config git-ftp.password secr3t
273 $ git config git-ftp.syncroot path/dir
274 $ git config git-ftp.cacert caCertStore
275 $ git config git-ftp.deployedsha1file mySHA1File
276 $ git config git-ftp.insecure 1
277 $ git config git-ftp.key ~/.ssh/id_rsa
278 $ git config git-ftp.keychain user@example.com
279 $ git config git-ftp.remote-root htdocs
280 After setting those defaults, push to john@ftp.example.com is as simple
282 as
283 $ git ftp push
285
287 Need different config defaults per each system or environment? Use the
288 so called scope feature.
289 Useful if you use multi environment development. Like a development,
291 testing and a production environment.
292 $ git config git-ftp.<scope>.<(url|user|password|syncroot|cacert)> <value>
294 So in the case below you would set a testing scope and a production
296 scope.
297 Here we set the params for the scope “testing”
299 $ git config git-ftp.testing.url ftp.testing.com:8080/foobar-path
301 $ git config git-ftp.testing.password simp3l
302 Here we set the params for the scope “production”
304 $ git config git-ftp.production.user manager
306 $ git config git-ftp.production.url live.example.com
307 $ git config git-ftp.production.password n0tThatSimp3l
308 Pushing to scope testing alias john@ftp.testing.com:8080/foobar-path
310 using password simp3l
311 $ git ftp push -s testing
313 Note: The SCOPE feature can be mixed with the DEFAULTS feature. Be‐
315 cause we didn't set the user for this scope, git-ftp uses john as user
316 as set before in DEFAULTS.
317 Pushing to scope production alias manager@live.example.com using pass‐
319 word n0tThatSimp3l
320 $ git ftp push -s production
322 Hint: If your scope name is identical with your branch name. You can
324 skip the scope argument, e.g. if your current branch is “production”:
325 $ git ftp push -s
327 You can also create scopes using the add-scope action. All settings
329 can be defined in the URL. Here we create the production scope using
330 add-scope
331 $ git ftp add-scope production ftp://manager:n0tThatSimp3l@live.example.com/foobar-path
333 Deleting scopes is easy using the remove-scope action.
335 $ git ftp remove-scope production
337
339 Add patterns to .git-ftp-ignore and all matching file names will be ig‐
340 nored. The patterns are interpreted as shell glob patterns since ver‐
341 sion 1.1.0. Before version 1.1.0, patterns were interpreted as regular
342 expressions. Here are some glob pattern examples:
343 Ignoring everything in a directory named config:
345 config/*
347 Ignoring all files having extension .txt:
349 *.txt
351 Ignoring a single file called foobar.txt:
353 foobar.txt
355 Ignoring Git related files:
357 .gitignore
359 */.gitignore # ignore files in sub directories
360 */.gitkeep
361 .git-ftp-ignore
362 .git-ftp-include
363 .gitlab-ci.yml
364
366 The .git-ftp-include file specifies intentionally untracked files that
367 Git-ftp should upload. If you have a file that should always be up‐
368 loaded, add a line beginning with ! followed by the file's name. For
369 example, if you have a file called VERSION.txt then add the following
370 line:
371 !VERSION.txt
373 If you have a file that should be uploaded whenever a tracked file
375 changes, add a line beginning with the untracked file's name followed
376 by a colon and the tracked file's name. For example, if you have a CSS
377 file compiled from an SCSS file then add the following line:
378 css/style.css:scss/style.scss
380 If you have multiple source files, you can add multiple lines for each
382 of them. Whenever one of the tracked files changes, the upload of the
383 paired untracked file will be triggered.
384 css/style.css:scss/style.scss
386 css/style.css:scss/mixins.scss
387 If a local untracked file is deleted, any change of a paired tracked
389 file will trigger the deletion of the remote file on the server.
390 All paths are usually relative to the Git working directory. When us‐
392 ing the --syncroot option, paths of tracked files (right side of the
393 colon) are relative to the set syncroot. Example:
394 # upload "html/style.css" triggered by html/style.scss
396 # with syncroot "html"
397 html/style.css:style.scss
398 If your source file is outside the syncroot, prefix it with a / and de‐
400 fine a path relative to the Git working directory. For example:
401 # upload "dist/style.css" with syncroot "dist"
403 dist/style.css:/src/style.scss
404 It is also possible to upload whole directories. For example, if you
406 use a package manager like composer, you can upload all vendor packages
407 when the file composer.lock changes:
408 vendor/:composer.lock
410 But keep in mind that this will upload all files in the vendor folder,
412 even those that are on the server already. And it will not delete
413 files from that directory if local files are deleted.
414
416 WARNING: It can delete local untracked files that are not listed in
417 your .git-ftp-ignore file.
418 You can use git-ftp to download from the remote host into your reposi‐
420 tory. You will need to install the lftp command line tool for that.
421 git ftp download
423 It uses lftp's mirror command to download all files that are different
425 on the remote host. You can inspect the changes with git-diff. But if
426 you have some local commits that have not been uploaded to the remote
427 host, you may not compare to the right version. You need to compare
428 the downloaded files to the commit that was uploaded last. This magic
429 is done automatically by
430 git ftp pull
432 It does the following steps for you:
434 git checkout <remote-commit>
436 git ftp download
437 git add --all
438 git commit -m '[git-ftp] remotely untracked modifications'
439 git ftp catchup
440 git checkout <my-branch>
441 git merge <new-remote-commit>
442 If you want to inspect the downloaded changes before merging them into
444 your current branch, add the option --no-commit. It will stop during
445 the merge at the end of the pull action. You can inspect the merge re‐
446 sult first and can then decide to continue or abort.
447 git ftp pull --no-commit
449 # inspect the result and commit them
450 git commit
451 # or abort the merge
452 git merge --abort
453 If you abort the merge, the downloaded changes will stay in an unrefer‐
455 enced commit until the Git garbage collector is run. The commit id
456 will be printed so that you can tag it or create a new branch.
457
459 This feature is experimental. The interface may change.
460 Git-ftp supports client-side hook scripts during the init and the push
462 action.
463 pre-ftp-push is called just before the upload to the server starts, but
465 after the changeset of files was generated. It can be bypassed with
466 the –no-verify option.
467 The hook is called with four parameters. The first is the used scope
469 or the host name if no scope is used. The second parameter is the des‐
470 tination URL. The third is the local commit id which is going to be
471 uploaded and the fourth is the remote commit id on the server which is
472 going to be updated.
473 The standard input is a list of all filenames to sync. Each file is
475 preceeded by A or D followed by a space. A means that this file is
476 scheduled for upload, D means it's scheduled for deletion. All entries
477 are separated by the NUL byte. This list is different to git diff, be‐
478 cause it has been changed by the rules of the .git-ftp-include file and
479 the .git-ftp-ignore file.
480 Exiting with non-zero status from this script causes Git-ftp to abort
482 and exit with status 9.
483 An example script is:
485 #!/bin/bash
487 #
488 # An example hook script to verify what is about to be uploaded.
489 #
490 # Called by "git ftp push" after it has checked the remote status, but before
491 # anything has been pushed. If this script exits with a non-zero status nothing
492 # will be pushed.
493 #
494 # This hook is called with the following parameters:
495 #
496 # $1 -- Scope name if set or host name of the remote
497 # $2 -- URL to which the upload is being done
498 # $3 -- Local commit id which is being uploaded
499 # $4 -- Remote commit id which is on the server
500 #
501 # Information about the files which are being uploaded or deleted is supplied
502 # as NUL separated entries to the standard input in the form:
503 #
504 # <status> <path>
505 #
506 # The status is either A for upload or D for delete. The path contains the
507 # path to the local file. It contains the syncroot if set.
508 #
509 # This sample shows how to prevent upload of files containing the word TODO.
510 remote="$1"
512 url="$2"
513 local_sha="$3"
514 remote_sha="$4"
515 while read -r -d '' status file
517 do
518 if [ "$status" = "A" ]
519 then
520 if grep 'TODO' "$file"; then
521 echo "TODO found in file $file, not uploading."
522 exit 1
523 fi
524 fi
525 done
526 exit 0
528 post-ftp-push is called after the transfer has been finished. The
530 standard input is empty, but the parameters are the same as given to
531 the pre-ftp-push hook. This hook is not bypassed by the –no-verify op‐
532 tion. It is meant primarily for notification and its exit status does
533 not have any effect.
534
536 In the backend, Git-ftp uses curl. This means ~/.netrc could be used
537 beside the other options of Git-ftp to authenticate.
538 $ editor ~/.netrc
540 machine ftp.example.com
541 login john
542 password SECRET
543
545 There are a bunch of different error codes and their corresponding er‐
546 ror messages that may appear during bad conditions. At the time of
547 this writing, the exit codes are:
548 1 Unknown error
550 2 Wrong Usage
552 3 Missing arguments
554 4 Error while uploading
556 5 Error while downloading
558 6 Unknown protocol
560 7 Remote locked
562 8 Not a Git project
564 9 The pre-ftp-push hook failed
566 10 A local file operation like cd or mkdir failed
568
570 The upstream BTS can be found at <https://github.com/git-ftp/git-
571 ftp/issues>.
572
574 Git-ftp was started by Rene Moser and is currently maintained by Maikel
575 Linke. Numerous conributions have come from Github users. See the AU‐
576 THORS file for an incomplete list of contributors.
577Git-ftp 1.5.1 2018-05-15 GIT-FTP(1)