1GIT-FTP(1)                                                          GIT-FTP(1)
2
3
4
5       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

NAME

10       Git-ftp - Git powered FTP client written as shell script.
11

SYNOPSIS

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

DESCRIPTION

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
20       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
24       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

ACTIONS

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
32       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
37       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
44       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
50       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
56       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
62       show   Downloads last uploaded SHA1 from log and hooks `git show`.
63
64       log    Downloads last uploaded SHA1 from log and hooks `git log`.
65
66       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
71       remove-scope <scope>
72              Remove a scope.
73
74       help   Shows a help screen.
75

OPTIONS

77       -u [username], --user [username]
78              FTP login name.  If no argument is given,  local  user  will  be
79              taken.
80
81       -p [password], --passwd [password]
82              FTP password.  See -P for interactive password prompt.  (note)
83
84       -P, --ask-passwd
85              Ask for FTP password interactively.
86
87       -k [[account]@[host]], --keychain [[account]@[host]]
88              FTP password from KeyChain (macOS only).
89
90       -a, --all
91              Uploads all files of current Git checkout.
92
93       -c, --commit
94              Sets SHA1 hash of last deployed commit by option.
95
96       -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
102       -b [branch], --branch [branch]
103              Push a specific branch
104
105       -s [scope], --scope [scope]
106              Using a scope  (e.g. dev,  production,  testing,  foobar).   See
107              SCOPE and DEFAULTS section for more information.
108
109       -l, --lock
110              Enable remote locking.
111
112       -D, --dry-run
113              Does  not  upload or delete anything, but tries to get the .git-
114              ftp.log file from remote host.
115
116       -f, --force
117              Does not ask any questions, it just does.
118
119       -n, --silent
120              Be silent.
121
122       -h, --help
123              Prints some usage information.
124
125       -v, --verbose
126              Be verbose.
127
128       -vv    Be as verbose as possible.  Useful for debug information.
129
130       --remote-root
131              Specifies the remote root directory to deploy  to.   The  remote
132              path in the URL is ignored.
133
134       --syncroot
135              Specifies  a  local directory to sync from as if it were the git
136              project root path.
137
138       --key  SSH private key file name for SFTP.
139
140       --pubkey
141              SSH public key file name.  Used with –key option.
142
143       --insecure
144              Don’t verify server’s certificate.
145
146       --cacert <file>
147              Use as CA certificate store.  Useful when a server has  a  self-
148              signed certificate.
149
150       --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
156       --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
162       --changed-only
163              During  the ftp mirror operation during a pull command, consider
164              only the files changed since the deployed commit.
165
166       --no-verify
167              Bypass the pre-ftp-push hook.  See HOOKS section.
168
169       --enable-post-errors
170              Fails if post-ftp-push raises an error.
171
172       --auto-init
173              Automatically run init action when running push action
174
175       --version
176              Prints version.
177
178       -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

URL

183       The scheme of an URL is what you would expect
184
185              protocol://host.domain.tld:port/path
186
187       Below  a full featured URL to host.example.com on port 2121 to path my‐
188       path using protocol ftp:
189
190              ftp://host.example.com:2121/mypath
191
192       But, there is not just FTP.  Supported protocols are:
193
194       ftp://...
195              FTP (default if no protocol is set)
196
197       sftp://...
198              SFTP
199
200       ftps://...
201              FTPS
202
203       ftpes://...
204              FTP over explicit SSL (FTPES) protocol
205

EXAMPLES

207   FIRST UPLOADS
208       Upload your files to an FTP server the first time:
209
210              $ git ftp init -u "john" -P "ftp://example.com/public_html"
211
212       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
219       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
224              $ git ftp init -u "john" --key "$HOME/.ssh/id_rsa" "sftp://example.com/~/public_html"
225
226       Otherwise it will use an absolute path, for example:
227
228              $ git ftp init -u "john" --key "$HOME/.ssh/id_rsa" "sftp://example.com/var/www"
229
230       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
235       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
241              $ ssh-keygen -y -f key.pem > key.pem.pub
242
243   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
247              $ git ftp catchup
248
249       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
253       After you stored the commit id of  the  uploaded  commit  via  init  or
254       catchup, you can then upload any new commits:
255
256              $ git ftp push
257
258       If you discovered a bug in the last uploaded version and you want to go
259       back by three commits:
260
261              $ git checkout HEAD~3
262              $ git ftp push
263
264       Or maybe some files got changed on the server and you  want  to  upload
265       all changes between branch master and branch develop:
266
267              $ git checkout develop         # This is the version which is uploaded.
268              $ git ftp push --commit master # Upload changes compared to master.
269

DEFAULTS

271       Don’t   repeat  yourself.   Setting  config  defaults  for  git-ftp  in
272       .git/config
273
274              $ git config git-ftp.<(url|user|password|syncroot|cacert|keychain|...)> <value>
275
276       Everyone likes examples:
277
278              $ 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
291       After setting those defaults, push to john@ftp.example.com is as simple
292       as
293
294              $ git ftp push
295
296       If  you run into issues with setting up your password please check this
297       note.
298

SCOPES

300       Need different config defaults per each system or environment?  Use the
301       so called scope feature.
302
303       Useful  if  you use multi environment development.  Like a development,
304       testing and a production environment.
305
306              $ git config git-ftp.<scope>.<(url|user|password|syncroot|cacert)> <value>
307
308       So in the case below you would set a testing  scope  and  a  production
309       scope.
310
311       Here we set the params for the scope “testing”
312
313              $ git config git-ftp.testing.url ftp.testing.com:8080/foobar-path
314              $ git config git-ftp.testing.password simp3l
315
316       Here we set the params for the scope “production”
317
318              $ 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
322       Pushing  to  scope  testing alias john@ftp.testing.com:8080/foobar-path
323       using password simp3l
324
325              $ git ftp push -s testing
326
327       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
331       Pushing to scope production alias manager@live.example.com using  pass‐
332       word n0tThatSimp3l
333
334              $ git ftp push -s production
335
336       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
339              $ git ftp push -s
340
341       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
345              $ git ftp add-scope production ftp://manager:n0tThatSimp3l@live.example.com/foobar-path
346
347       Deleting scopes is easy using the remove-scope action.
348
349              $ git ftp remove-scope production
350

IGNORING FILES TO BE SYNCED

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
357       Ignoring everything in a directory named config:
358
359              config/*
360
361       Ignoring all files having extension .txt:
362
363              *.txt
364
365       Ignoring a single file called foobar.txt:
366
367              foobar.txt
368
369       Ignoring Git related files:
370
371              .gitignore
372              */.gitignore      # ignore files in sub directories
373              */.gitkeep
374              .git-ftp-ignore
375              .git-ftp-include
376              .gitlab-ci.yml
377

SYNCING UNTRACKED FILES

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
385              !VERSION.txt
386
387       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
392              css/style.css:scss/style.scss
393
394       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
398              css/style.css:scss/style.scss
399              css/style.css:scss/mixins.scss
400
401       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
404       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
408              # upload "html/style.css" triggered by html/style.scss
409              # with syncroot "html"
410              html/style.css:style.scss
411
412       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
415              # upload "dist/style.css" with syncroot "dist"
416              dist/style.css:/src/style.scss
417
418       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
422              vendor/:composer.lock
423
424       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

DOWNLOADING FILES (EXPERIMENTAL)

429       WARNING: It can delete local untracked files that  are  not  listed  in
430       your .git-ftp-ignore file.
431
432       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
435              git ftp download
436
437       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
444              git ftp pull
445
446       It does the following steps for you:
447
448              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
456       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
461              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
467       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

HOOKS (EXPERIMENTAL)

472       This feature is experimental.  The interface may change.
473
474       Git-ftp supports client-side hook scripts during the init and the  push
475       action.
476
477       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
481       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
487       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
494       Exiting with non-zero status from this script causes Git-ftp  to  abort
495       and exit with status 9.
496
497       An example script is:
498
499              #!/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
524              remote="$1"
525              url="$2"
526              local_sha="$3"
527              remote_sha="$4"
528
529              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
540              exit 0
541
542       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

PASSWORDS

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
553              --passwd '#my$fancy!secret'
554
555       Mostly --ask-passwd works even if --passwd does not work.  So maybe you
556       can give this a try.
557
558       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
564       Quoting also works if a default is set with git config:
565
566              $ git config git-ftp.password '#my$fancy!secret'
567
568   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
572              $ editor ~/.netrc
573              machine ftp.example.com
574              login john
575              password SECRET
576
577       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
581              git ftp init ftp.example.com
582
583       Of  course this can be combined with the defaults feature to set config
584       defaults for other options as well.
585
586   Keychain on macOS
587       On macOS you can use the built in keychain to store and get your  pass‐
588       words.
589
590       You  can  use  this feature by using the option --keychain in your com‐
591       mand:
592
593              $ git ftp init --keychain account@host ftpes://host
594
595       You can omit the value for this option.  Then git-ftp  will  guess  the
596       account and hostname from user and url.
597
598       Or  you can set a config for this, so you don’t need to repeat yourself
599       (see defaults for details):
600
601              $ git config git-ftp.keychain account@host
602
603       You can omit the hostname here.  If there is no @ in the  config  value
604       git-ftp will guess the hostname from url.
605
606       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
611       If your password is not in your keychain yet it is  recommended  adding
612       it using the following command:
613
614              $ security add-internet-password -a account -r "ftp " -s host -w secr3t
615
616       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
622       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
629       Please  not  that  the keychain entry can not be used for password pro‐
630       tected private keys in SSH.
631

EXIT CODES

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
637       1      Unknown error
638
639       2      Wrong Usage
640
641       3      Missing arguments
642
643       4      Error while uploading
644
645       5      Error while downloading
646
647       6      Unknown protocol
648
649       7      Remote locked
650
651       8      Not a Git project
652
653       9      The pre-ftp-push hook failed
654
655       10     A local file operation like cd or mkdir failed
656

KNOWN ISSUES & BUGS

658       The upstream  BTS  can  be  found  at  <https://github.com/git-ftp/git-
659       ftp/issues>.
660

AUTHORS

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.
665
666
667
668Git-ftp 1.6.0                     2020-02-03                        GIT-FTP(1)
Impressum