@ -8,28 +8,43 @@ Git-ftp - Git powered FTP client written as shell script.
# SYNOPSIS
git-ftp [actions] [options] [url]...
*git-ftp* \<action\> [\<options\>] [\<url\>]
# DESCRIPTION
Git-ftp is a FTP client using Git to determine which local files to upload or which files should be deleted on the remote host.
Git-ftp is a FTP client using [Git] to determine which local files to upload or
which files to delete on the remote host.
It saves the deployed state by uploading the SHA1 hash in the .git-ftp.log file. There is no need for [Git] to be installed on the remote host.
It saves the deployed state by uploading the SHA1 hash in the .git-ftp.log file.
There is no need for Git to be installed on the remote host.
Even if you play with different branches, git-ftp knows which files are different and only handles those files. No ordinary FTP client can do this and it saves time and bandwidth.
Another advantage is Git-ftp only handles files which are tracked with [Git].
Even if you play with different branches, git-ftp knows which files are
different and handles only those files. That saves time and bandwidth.
# ACTIONS
`init`
: Initializes the first upload to remote host.
: Uploads all git-tracked non-ignored files to the remote server and
creates the .git-ftp.log file containing the SHA1 of the latest commit.
`catchup`
: Creates or updates the .git-ftp.log file on the remote host.
It assumes that you uploaded all other files already.
You might have done that with another program.
`push`
: Uploads files which have changed since last upload.
: Uploads files that have changed and
deletes files that have been deleted since the last upload.
`catchup`
: Uploads the .git-ftp.log file only. We have already uploaded the files to remote host with a different program and want to remember its state by uploading the .git-ftp.log file.
`download`
: Downloads changes from the remote host into your working tree.
This feature needs lftp to be installed and does not use any power of
Git.
`pull`
: Downloads changes from the remote host into a separate commit
and merges that into your current branch.
This feature needs lftp to be installed.
`show`
: Downloads last uploaded SHA1 from log and hooks \`git show\`.
@ -38,13 +53,15 @@ Another advantage is Git-ftp only handles files which are tracked with [Git].
: Downloads last uploaded SHA1 from log and hooks \`git log\`.
`add-scope <scope>`
: Creates a new scope (e.g. dev, production, testing, foobar). This is a wrapper action over git-config. See **SCOPES** section for more information.
: Creates a new scope (e.g. dev, production, testing, foobar).
This is a wrapper action over git-config.
See **SCOPES** section for more information.
`remove-scope <scope>`
: Remove a scope.
`help`
: Prints a usage help.
: Shows a help screen.
# OPTIONS
@ -70,13 +87,15 @@ Another advantage is Git-ftp only handles files which are tracked with [Git].
: Push a specific branch
`-s [scope]`, `--scope [scope]`
: Using a scope (e.g. dev, production, testing, foobar). See **SCOPE** and **DEFAULTS** section for more information.
: Using a scope (e.g. dev, production, testing, foobar). See **SCOPE**
and **DEFAULTS** section for more information.
`-l`, `--lock`
: Enable remote locking.
`-D`, `--dry-run`
: Does not upload or delete anything, but tries to get the .git-ftp.log file from remote host.
: Does not upload or delete anything, but tries to get the .git-ftp.log
file from remote host.
`-f`, `--force`
: Does not ask any questions, it just does.
@ -94,10 +113,12 @@ Another advantage is Git-ftp only handles files which are tracked with [Git].
: Be as verbose as possible. Useful for debug information.
`--remote-root`
: Specifies the remote root directory to deploy to. The remote path in the URL is ignored.
: Specifies the remote root directory to deploy to.
The remote path in the URL is ignored.
`--syncroot`
: Specifies a local directory to sync from as if it were the git project root path.
: Specifies a local directory to sync from as if it were the git project
root path.
`--key`
: SSH private key file name.
@ -109,10 +130,17 @@ Another advantage is Git-ftp only handles files which are tracked with [Git].
: Don't verify server's certificate.
`--cacert <file>`
: Use <file> as CA certificate store. Useful when a server has got a self-signed certificate.
: Use <file> as CA certificate store.
Useful when a server has a self-signed certificate.
`--disable-epsv`
: Tell curl to disable the use of the EPSV command when doing passive FTP transfers. Curl will normally always first attempt to use EPSV before PASV, but with this option, it will not try using EPSV.
: Tell curl to disable the use of the EPSV command when doing passive FTP
transfers.
Curl will normally always first attempt to use EPSV before PASV,
but with this option, it will not try using EPSV.
`--no-commit`
: Stop while merging downloaded changes during the pull action.
`--version`
: Prints version.
@ -123,7 +151,8 @@ 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*:
Below a full featured URL to *host.example.com* on port *2121* to path *mypath*
using protocol *ftp*:
ftp://host.example.com:2121/mypath
@ -165,9 +194,11 @@ After setting those defaults, push to *john@ftp.example.com* is as simple as
# SCOPES
Need different config defaults per each system or environment? Use the so called scope feature.
Need different config defaults per each system or environment? Use the so
called scope feature.
Useful if you use multi environment development. Like a development, testing and a production environment.
Useful if you use multi environment development. Like a development, testing
Pushing to scope *testing* alias *john@ftp.testing.com:8080/foobar-path* using password *simp3l*
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**.
*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**.
Pushing to scope *production* alias *manager@live.example.com* using
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":
*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.
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
@ -227,42 +263,96 @@ Ignoring a single file called `foobar.txt`:
# 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.
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:
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.
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, a paired tracked file will trigger the deletion of the remote file on the server.
If a local untracked file is deleted, a paired tracked file will trigger the
deletion of the remote file on the server.
When using the `--syncroot` option, all paths are relative to the set syncroot.
If your source file is outside the syncroot, add a / and define a path relative to the Git working directory.
If your source file is outside the syncroot, add a / and define a path relative
to the Git working directory.
# upload "dist/style.css" with syncroot "dist"
style.css:/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:
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.
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
You can use git-ftp to download the 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.
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.
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.
# NETRC
In the backend, Git-ftp uses curl. This means `~/.netrc` could be used beside the other options of Git-ftp to authenticate.
In the backend, Git-ftp uses curl.
This means `~/.netrc` could be used beside the other options of Git-ftp
to authenticate.
$ editor ~/.netrc
machine ftp.example.com
@ -271,7 +361,9 @@ In the backend, Git-ftp uses curl. This means `~/.netrc` could be used beside th
# 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:
There are a bunch of different error codes and their corresponding error
Maikel Linke
9 years ago