1GIT-FTP(1) GIT-FTP(1)
2
3
4
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
16 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
20 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
28 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
33 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 git ftp
37 push: LFS link files will be replaced with large files so they
38 can be uploaded.
39
40 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
46 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
51 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
57 show Downloads last uploaded SHA1 from log and hooks `git show`.
58
59 log Downloads last uploaded SHA1 from log and hooks `git log`.
60
61 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
66 remove-scope <scope>
67 Remove a scope.
68
69 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
76 -p [password], --passwd [password]
77 FTP password. See -P for interactive password prompt.
78
79 -P, --ask-passwd
80 Ask for FTP password interactively.
81
82 -k [[user]@[account]], --keychain [[user]@[account]]
83 FTP password from KeyChain (Mac OS X only).
84
85 -a, --all
86 Uploads all files of current Git checkout.
87
88 -c, --commit
89 Sets SHA1 hash of last deployed commit by option.
90
91 -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
97 -b [branch], --branch [branch]
98 Push a specific branch
99
100 -s [scope], --scope [scope]
101 Using a scope (e.g. dev, production, testing, foobar). See
102 SCOPE and DEFAULTS section for more information.
103
104 -l, --lock
105 Enable remote locking.
106
107 -D, --dry-run
108 Does not upload or delete anything, but tries to get the
109 .git-ftp.log file from remote host.
110
111 -f, --force
112 Does not ask any questions, it just does.
113
114 -n, --silent
115 Be silent.
116
117 -h, --help
118 Prints some usage information.
119
120 -v, --verbose
121 Be verbose.
122
123 -vv Be as verbose as possible. Useful for debug information.
124
125 --remote-root
126 Specifies the remote root directory to deploy to. The remote
127 path in the URL is ignored.
128
129 --syncroot
130 Specifies a local directory to sync from as if it were the git
131 project root path.
132
133 --key SSH private key file name for SFTP.
134
135 --pubkey
136 SSH public key file name. Used with –key option.
137
138 --insecure
139 Don’t verify server’s certificate.
140
141 --cacert <file>
142 Use as CA certificate store. Useful when a server has a
143 self-signed certificate.
144
145 --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
151 --no-commit
152 Stop while merging downloaded changes during the pull action.
153
154 --changed-only
155 During the ftp mirror operation during a pull command, consider
156 only the files changed since the deployed commit.
157
158 --no-verify
159 Bypass the pre-ftp-push hook. See HOOKS section.
160
161 --enable-post-errors
162 Fails if post-ftp-push raises an error.
163
164 --auto-init
165 Automatically run init action when running push action
166
167 --version
168 Prints version.
169
170 -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
177 protocol://host.domain.tld:port/path
178
179 Below a full featured URL to host.example.com on port 2121 to path my‐
180 path using protocol ftp:
181
182 ftp://host.example.com:2121/mypath
183
184 But, there is not just FTP. Supported protocols are:
185
186 ftp://...
187 FTP (default if no protocol is set)
188
189 sftp://...
190 SFTP
191
192 ftps://...
193 FTPS
194
195 ftpes://...
196 FTP over explicit SSL (FTPES) protocol
197
199 FIRST UPLOADS
200 Upload your files to an FTP server the first time:
201
202 $ git ftp init -u "john" -P "ftp://example.com/public_html"
203
204 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
211 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
216 $ git ftp init -u "john" --key "$HOME/.ssh/id_rsa" "sftp://example.com/~/public_html"
217
218 Otherwise it will use an absolute path, for example:
219
220 $ git ftp init -u "john" --key "$HOME/.ssh/id_rsa" "sftp://example.com/var/www"
221
222 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
227 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
233 $ ssh-keygen -y -f key.pem > key.pem.pub
234
235 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
239 $ git ftp catchup
240
241 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
245 After you stored the commit id of the uploaded commit via init or
246 catchup, you can then upload any new commits:
247
248 $ git ftp push
249
250 If you discovered a bug in the last uploaded version and you want to go
251 back by three commits:
252
253 $ git checkout HEAD~3
254 $ git ftp push
255
256 Or maybe some files got changed on the server and you want to upload
257 all changes between branch master and branch develop:
258
259 $ 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
266 $ git config git-ftp.<(url|user|password|syncroot|cacert|keychain|...)> <value>
267
268 Everyone likes examples:
269
270 $ 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
281 After setting those defaults, push to john@ftp.example.com is as simple
282 as
283
284 $ git ftp push
285
287 Need different config defaults per each system or environment? Use the
288 so called scope feature.
289
290 Useful if you use multi environment development. Like a development,
291 testing and a production environment.
292
293 $ git config git-ftp.<scope>.<(url|user|password|syncroot|cacert)> <value>
294
295 So in the case below you would set a testing scope and a production
296 scope.
297
298 Here we set the params for the scope “testing”
299
300 $ git config git-ftp.testing.url ftp.testing.com:8080/foobar-path
301 $ git config git-ftp.testing.password simp3l
302
303 Here we set the params for the scope “production”
304
305 $ 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
309 Pushing to scope testing alias john@ftp.testing.com:8080/foobar-path
310 using password simp3l
311
312 $ git ftp push -s testing
313
314 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
318 Pushing to scope production alias manager@live.example.com using pass‐
319 word n0tThatSimp3l
320
321 $ git ftp push -s production
322
323 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
326 $ git ftp push -s
327
328 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
332 $ git ftp add-scope production ftp://manager:n0tThatSimp3l@live.example.com/foobar-path
333
334 Deleting scopes is easy using the remove-scope action.
335
336 $ 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
344 Ignoring everything in a directory named config:
345
346 config/*
347
348 Ignoring all files having extension .txt:
349
350 *.txt
351
352 Ignoring a single file called foobar.txt:
353
354 foobar.txt
355
356 Ignoring Git related files:
357
358 .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
372 !VERSION.txt
373
374 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
379 css/style.css:scss/style.scss
380
381 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
385 css/style.css:scss/style.scss
386 css/style.css:scss/mixins.scss
387
388 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
391 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
395 # upload "html/style.css" triggered by html/style.scss
396 # with syncroot "html"
397 html/style.css:style.scss
398
399 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
402 # upload "dist/style.css" with syncroot "dist"
403 dist/style.css:/src/style.scss
404
405 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
409 vendor/:composer.lock
410
411 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
419 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
422 git ftp download
423
424 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
431 git ftp pull
432
433 It does the following steps for you:
434
435 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
443 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
448 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
454 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
461 Git-ftp supports client-side hook scripts during the init and the push
462 action.
463
464 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
468 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
474 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
481 Exiting with non-zero status from this script causes Git-ftp to abort
482 and exit with status 9.
483
484 An example script is:
485
486 #!/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
511 remote="$1"
512 url="$2"
513 local_sha="$3"
514 remote_sha="$4"
515
516 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
527 exit 0
528
529 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
539 $ 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
549 1 Unknown error
550
551 2 Wrong Usage
552
553 3 Missing arguments
554
555 4 Error while uploading
556
557 5 Error while downloading
558
559 6 Unknown protocol
560
561 7 Remote locked
562
563 8 Not a Git project
564
565 9 The pre-ftp-push hook failed
566
567 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.
577
578
579
580Git-ftp 1.5.1 2018-05-15 GIT-FTP(1)