保姆级教程：在Ubuntu 20.04上用Git和Qt Creator搞定Gitee代码同步（含SSH-Askpass报错解决）

Ubuntu 20.04下Qt项目与Gitee无缝集成的全流程指南

在Linux环境下进行Qt开发时，版本控制与远程仓库的协同工作往往成为新手开发者的第一个"拦路虎"。不同于Windows或macOS的图形化操作，Ubuntu系统下的Git配置需要更多命令行介入，而Qt Creator的Git集成又存在一些特有的"坑点"。本文将带你完整走通从零开始配置到最终实现Qt Creator与Gitee无缝协作的全过程，特别针对Ubuntu 20.04 LTS环境中的典型问题提供解决方案。

1. 环境准备与基础配置

在开始之前，我们需要确保系统环境满足基本要求。Ubuntu 20.04默认的软件源可能不是最新版本，建议先更新系统：

sudo apt update && sudo apt upgrade -y

1.1 Git安装与基础配置

虽然Ubuntu预装了Git，但版本可能较旧。建议安装最新稳定版：

sudo add-apt-repository ppa:git-core/ppa -y sudo apt install git -y git --version # 验证安装，推荐2.25.1以上版本

全局Git配置是后续所有操作的基础，务必正确设置用户信息：

git config --global user.name "YourName" git config --global user.email "your.email@example.com" git config --global core.editor nano # 推荐使用nano而非默认的vi

小技巧：使用git config --list可以查看当前所有配置项，--show-origin参数能显示每个配置项的来源文件。

1.2 SSH密钥生成与Gitee绑定

为避免每次操作都需要输入密码，推荐使用SSH协议连接Gitee：

ssh-keygen -t ed25519 -C "your.email@example.com" # 生成更安全的Ed25519密钥 cat ~/.ssh/id_ed25519.pub # 复制公钥内容

登录Gitee，进入"设置"→"SSH公钥"，粘贴公钥内容。测试连接：

ssh -T git@gitee.com

注意：如果遇到连接问题，可能是防火墙或网络设置导致，可尝试ssh -vT git@gitee.com查看详细调试信息。

2. 本地Qt项目初始化与版本控制

2.1 项目结构规范化

在开始版本控制前，建议先规范项目结构。典型的Qt项目应包含：

MyProject/ ├── .gitignore # Git忽略规则 ├── MyProject.pro # Qt项目文件 ├── src/ # 源代码目录 ├── include/ # 头文件目录 └── resources/ # 资源文件

创建合适的.gitignore文件至关重要，可避免将构建生成文件等纳入版本控制。推荐使用Qt专用的gitignore模板：

curl https://raw.githubusercontent.com/github/gitignore/main/Qt.gitignore -o .gitignore

2.2 Git仓库初始化

在项目根目录执行：

git init git add .gitignore git commit -m "Initial commit with basic structure"

常见问题：如果遇到fatal: unable to auto-detect email address错误，说明未正确配置全局用户信息，请返回1.1节检查配置。

3. Gitee远程仓库操作全流程

3.1 创建Gitee仓库

在Gitee官网点击"新建仓库"，注意：

• 仓库名称建议与本地项目名一致
• 不要初始化README、.gitignore等文件（以免与本地冲突）
• 选择私有或公开根据项目需求决定

创建后，复制仓库的SSH地址（形如git@gitee.com:yourname/repo.git）

3.2 本地与远程仓库关联

在本地项目目录执行：

git remote add origin git@gitee.com:yourname/repo.git git branch -M main # 将默认分支改名为main git push -u origin main

重要提示：如果远程仓库已有内容（如README文件），需要先执行git pull origin main --allow-unrelated-histories合并历史记录。

3.3 分支管理策略

推荐采用Git Flow简化分支管理：

git checkout -b develop # 创建并切换到开发分支 git push -u origin develop

日常开发应在feature分支进行：

git checkout develop git pull git checkout -b feature/new-module # 开发完成后... git add . git commit -m "Implement new module" git checkout develop git merge --no-ff feature/new-module git branch -d feature/new-module git push origin develop

4. Qt Creator深度集成配置

4.1 Git插件基础设置

打开Qt Creator，进入"工具"→"选项"→"版本控制"→"Git"：

• 设置Git可执行文件路径（通常为/usr/bin/git）
• 启用"自动拉取"和"自动推送"（可选）
• 配置提交时的默认作者信息

4.2 解决SSH-Askpass问题

这是Ubuntu下Qt Creator最常见的Git相关问题，表现为push时出现：

error: cannot run ssh-askpass: No such file or directory

解决方案是安装必要的组件并配置SSH代理：

sudo apt install ssh-askpass-gnome eval $(ssh-agent) # 启动SSH代理 ssh-add ~/.ssh/id_ed25519 # 添加密钥到代理

为了让Qt Creator能识别SSH代理，需要在~/.bashrc末尾添加：

export SSH_ASKPASS=/usr/bin/ssh-askpass export DISPLAY=:0

然后重启Qt Creator使其获取新的环境变量。

4.3 工作流优化技巧

1. 快捷键配置：为常用Git操作设置快捷键（如提交、推送、拉取）
2. 提交模板：创建~/.gitmessage作为默认提交信息模板
3. 差异查看：利用Qt Creator内置的差异工具进行代码审查
4. 分支切换：通过左下角的Git分支选择器快速切换分支

5. 高级问题排查与性能优化

5.1 常见错误解决方案

问题1：fatal: The current branch has no upstream branch

解决方案：

git push --set-upstream origin branch-name

问题2：Permission denied (publickey)

解决方案：

chmod 600 ~/.ssh/id_ed25519 ssh-add -l # 检查密钥是否已加载

问题3：Qt Creator无法识别Git仓库

解决方案：

• 关闭并重新打开项目
• 检查项目目录是否包含.git文件夹
• 在Qt Creator中手动指定VCS类型为Git

5.2 仓库性能优化

对于大型Qt项目，可以考虑以下优化措施：

git config --global core.preloadindex true # 启用索引预加载 git config --global core.fscache true # 启用文件系统缓存 git config --global pack.threads 4 # 多线程打包

对于包含大量二进制文件的项目，建议使用Git LFS：

sudo apt install git-lfs git lfs install git lfs track "*.bin" "*.zip" # 跟踪特定二进制文件类型

6. 自动化脚本与持续集成

6.1 提交前检查脚本

在.git/hooks/pre-commit中创建脚本，实现自动代码格式化：

#!/bin/sh find . -name '*.cpp' -o -name '*.h' | xargs clang-format -i git add -u

记得给脚本添加执行权限：chmod +x .git/hooks/pre-commit

6.2 Gitee CI/CD配置

在项目根目录创建.gitee-ci.yml文件，配置自动化构建：

image: ubuntu:20.04 stages: - build qt_build: stage: build script: - apt update && apt install -y qt5-default g++ make - qmake - make artifacts: paths: - build/

6.3 定时任务自动化

使用cron定时拉取最新代码并构建：

0 * * * * cd /path/to/project && git pull && qmake && make

对于更复杂的自动化需求，可以考虑使用Jenkins或GitLab Runner搭建完整的CI/CD流水线。