You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 7ee1154
Browse filesBrowse the repository at this point in the historyBrowse files
Unlike typical CI/CD actions, this tool operates independently of remote Git hosts (like GitHub or GitLab). It is designed to deploy changes directly from your local machine to your server, ensuring only files that have changed (added, modified, or deleted) since the last deployment are transferred.
8
+
> **Deploy only what changed.** A fast, git-diff-powered CLI tool that syncs your local git project to a remote server via FTP, FTPS, or SFTP — no CI/CD pipeline required.
6
9
7
-
## Features
10
+
---
11
+
12
+
## Why local-git-deploy?
13
+
14
+
Most FTP/SFTP deploy tools re-upload your entire project on every run. `local-git-deploy` uses `git diff` to detect **only the files that changed** since your last deployment, making it:
15
+
16
+
- ⚡ **Fast** — uploads only changed files, not the whole project
17
+
- 🔒 **Secure** — keeps passwords and private keys out of your repo
18
+
- 🧹 **Clean** — automatically deletes removed or renamed files on the remote server
19
+
- 🖥️ **Local-first** — works from your machine, no GitHub Actions or CI server needed
20
+
- 🏠 **Shared hosting friendly** — perfect for cPanel, FTP-only hosts, and PHP projects
8
21
9
-
-**Git Diff Powered:** Uses `git diff` to determine exactly which files have been modified or added, drastically speeding up deployments.
10
-
-**State Tracking:** Maintains a `.deploy-sync-state` file on your server to track the last deployed commit.
11
-
-**Handles Deletions & Renames:** Automatically removes deleted or renamed files on the remote server to keep it clean.
12
-
-**Secure Handling:** Supports `.env` to keep passwords and private keys out of your Git history.
13
-
-**Extensive Protocol Support:** FTP, FTPS, and SFTP.
22
+
---
14
23
15
24
## Installation
16
25
@@ -20,58 +29,112 @@ Install globally via npm:
20
29
npm install -g local-git-deploy
21
30
```
22
31
32
+
---
33
+
23
34
## Setup & Configuration
24
35
25
-
In the root of your git project, create a `local-git-deploy.yml` (or `.json`) file:
36
+
In the root of your git project, create a `local-git-deploy.yml` (or `.json`) configuration file:
26
37
27
38
```yaml
28
39
server: ftp.your-server.com
29
40
user: your_username
30
-
protocol: ftp # Options: ftp, ftps, sftp
31
-
port: 21# 21 for FTP, 22 for SFTP
41
+
protocol: ftp # Options: ftp | ftps | sftp
42
+
port: 21# 21 for FTP/FTPS, 22 for SFTP
32
43
remote_dir: /public_html
33
-
exclude: # Glob patterns to ignore
44
+
exclude: # Glob patterns to exclude from deployment
34
45
- ".env"
35
46
- "local-git-deploy.yml"
36
47
- "node_modules/**"
37
48
- ".git/**"
38
49
```
39
50
40
-
**Security Best Practice:**
41
-
Do **NOT** put your password in the YAML file. Instead, create a `.env` file in your project root (ensure `.env` is in your `.gitignore`!):
51
+
### Secure Credentials with `.env`
52
+
53
+
> **Security Best Practice:** Never put passwords in your YAML config. Use a `.env` file instead (and make sure `.env` is in your `.gitignore`).
42
54
43
55
```env
56
+
# FTP / FTPS password
44
57
DEPLOY_PASSWORD=your_super_secret_password
45
-
```
46
58
47
-
For SFTP with private keys:
48
-
49
-
```env
59
+
# SFTP private key (optional)
50
60
DEPLOY_PRIVATE_KEY_PATH=/path/to/private/key.pem
51
61
```
52
62
53
-
_Note: If your server uses SFTP and requires BOTH a private key and a passphrase (or password), simply provide both `DEPLOY_PASSWORD` and `DEPLOY_PRIVATE_KEY_PATH` in your `.env` file. The CLI will automatically use the password to unlock your key or satisfy the server's two-factor requirement._
63
+
_Tip: If your SFTP server requires both a private key and a passphrase, provide both `DEPLOY_PASSWORD` and `DEPLOY_PRIVATE_KEY_PATH`. The CLI handles both automatically._
64
+
65
+
---
54
66
55
67
## Usage
56
68
57
-
Commit your changes locally, then simply run:
69
+
Commit your changes locally, then run:
58
70
59
71
```bash
60
72
local-git-deploy
61
73
```
62
74
63
75
The CLI will:
64
76
65
-
1. Connect to your server.
66
-
2. Read the remote state file.
67
-
3. Compare the remote commit with your local `HEAD`.
68
-
4. Upload new files and delete removed files.
69
-
5. Update the remote state file to the new commit hash.
77
+
1. Connect to your remote server
78
+
2. Read the remote `.deploy-sync-state` file to find the last deployed commit
79
+
3. Run `git diff` between the remote commit and your local `HEAD`
80
+
4. Upload only new and modified files
81
+
5. Delete files that were removed or renamed
82
+
6. Update the remote state file with the new commit hash
83
+
84
+
---
85
+
86
+
## Protocol Support
87
+
88
+
| Protocol | Port | Use Case |
89
+
|----------|------|----------|
90
+
| `ftp` | 21 | Basic shared hosting |
91
+
| `ftps` | 21 | FTP with TLS/SSL (cPanel, etc.) |
92
+
| `sftp` | 22 | SSH-based secure file transfer |
93
+
94
+
---
95
+
96
+
## Features
97
+
98
+
- **Git-diff powered deploys** — only changed files are transferred
99
+
- **State tracking** — maintains a `.deploy-sync-state` file on the server to track the last deployed commit hash
100
+
- **Deletion & rename handling** — automatically cleans up removed or renamed files on the remote
- **Connection timeouts** — prevents hanging on unreachable servers
105
+
- **Self-signed cert support** — opt-in with `insecure: true` for FTPS on dev servers
106
+
- **Resume-safe** — if a deploy fails midway, run again and it picks up safely
107
+
108
+
---
70
109
71
110
## Troubleshooting
72
111
73
-
- If a deployment fails midway, the `.deploy-sync-state` will **not** update. This means you can simply fix the issue and run `local-git-deploy` again to safely resume.
112
+
**Deployment failed midway?**
113
+
No problem. The `.deploy-sync-state` only updates on a successful deploy. Just fix the issue and re-run `local-git-deploy` — it will re-attempt only the affected files.
114
+
115
+
**Getting a "bad object" error?**
116
+
This usually means the state file on the server has a stale or invalid commit hash. Delete the `.deploy-sync-state` file from your remote server and re-run to do a clean sync.
117
+
118
+
**Filenames with spaces not working?**
119
+
Make sure you are on `v1.1.1` or later. Special character support was added in that release.
120
+
121
+
---
122
+
123
+
## Contributing
124
+
125
+
Pull requests and issues are welcome! Please open an issue first to discuss any major changes.
126
+
127
+
- [Report a bug](https://github.com/pablo-codes/local-git-deploy/issues)
128
+
- [Request a feature](https://github.com/pablo-codes/local-git-deploy/issues)
Copy file name to clipboardExpand all lines: package.json
+17-2Lines changed: 17 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
{
2
2
"name": "local-git-deploy",
3
3
"version": "1.2.1",
4
-
"description": "CLI tool to sync a local git working directory with a remote FTP/SFTP server.",
4
+
"description": "CLI tool to deploy changed files from a local git working directory to a remote FTP, FTPS, or SFTP server. Fast git-diff-powered deployments for shared hosting.",
0 commit comments