GIS项目代码版本失控？Git入门必学这四招！（含：Gitee官网操作指南）

wowwwai GIS研习社 · 工具流程与项目排障

引言：如果你正在做课程设计、WebGIS 项目、ArcPy 脚本、QGIS 插件或空间数据处理代码，遇到“GIS项目代码版本失控？Git入门必学这四招！（含：Gitee官网操作指南）”这个问题并不奇怪。很多 GIS 项目一开始只是几个脚本，后来逐渐变成数据处理流程、地图服务配置、前端地图页面、数据库 SQL 和说明文档混在一起，最后靠“最终版”“最终修改版”“真的最终版”来管理，风险非常高。

本文面向 GIS 学生、初级 GIS 工程师和 WebGIS 开发者，重点讲清楚 Git 入门最实用的四招：初始化仓库、提交版本、创建分支、推送到 Gitee。你不需要先成为程序员，只要能理解“保存一个可回退的项目快照”，就能开始用 Git 管好 GIS 项目代码。

背景：为什么 GIS 项目特别容易代码版本失控

背景：GIS 项目的版本失控，通常不是因为大家不认真，而是因为 GIS 项目本身文件类型复杂、流程链条长、修改频率高。

一个常见的 GIS 项目文件夹可能同时包含：

• Python 脚本，例如批量裁剪栅格、矢量叠加分析、坐标转换脚本。
• WebGIS 前端代码，例如 Leaflet、OpenLayers、Cesium 页面。
• 后端接口代码，例如 Flask、Django、Node.js 地图服务接口。
• PostGIS SQL 脚本，例如建表、空间索引、视图和空间查询。
• 配置文件，例如地图服务地址、数据库连接参数、样式配置。
• 项目说明文档，例如数据来源、处理步骤、部署说明。

如果不用 Git，常见问题包括：

• 昨天还能运行的空间分析脚本，今天改完后报错，但不知道改了哪里。
• 同学或同事各自改了一份代码，最后不知道以谁的版本为准。
• WebGIS 页面改样式时，把地图加载逻辑也误删了。
• 部署到服务器后发现本地代码和服务器代码不一致。
• 项目交付时只有一堆压缩包，无法说明每次修改的原因。

Git 的价值就是把这些修改变成可追踪、可回退、可协作的记录。Gitee 则可以作为远程代码托管平台，让你的 GIS 项目不只保存在本地电脑里。

原理：Git 管理的不是“文件名版本”，而是“项目快照”

原理：很多初学者会把 Git 理解成网盘同步工具，这是一个常见误区。Git 的核心不是简单上传文件，而是记录一次次代码变化形成的项目快照。

你可以把 Git 理解成三个区域：

• 工作区：你正在编辑的 GIS 项目文件夹，例如 Python 脚本、HTML 页面、SQL 文件。
• 暂存区：准备纳入下一次版本记录的文件清单。
• 版本库：真正保存提交记录的地方，每次提交都有说明和唯一编号。

当你修改了一个 ArcPy 批处理脚本，Git 不会自动把它变成一个正式版本。你需要先把修改加入暂存区，再执行提交。这样做的好处是：你可以有选择地保存本次修改，而不是把所有临时文件、测试数据、缓存文件都混进版本记录。

对于 GIS 项目来说，一个好的提交记录应该描述清楚本次修改的目的，例如：

• 新增 GeoJSON 转 Shapefile 的批处理脚本。
• 修复 WebGIS 地图图层重复加载问题。
• 调整 PostGIS 空间索引创建脚本。
• 补充 QGIS 处理流程说明文档。

这样过一段时间回看项目历史时，你能快速知道每次改动解决了什么问题。

步骤：Git入门必学四招，适合 GIS 项目直接照做

步骤：下面用一个典型 GIS 项目为例。假设你的项目文件夹叫 gis-analysis-demo，里面有 Python 脚本、README 文档和一些配置文件。

第一招：初始化 Git 仓库

进入项目文件夹后，执行：

git init

这条命令会在当前文件夹中创建一个隐藏的 .git 目录。它就是 Git 保存版本历史的地方。

初始化后，可以查看当前状态：

git status

如果你看到很多未跟踪文件，说明 Git 已经识别到项目中的文件，但还没有把它们纳入版本管理。

对于 GIS 项目，建议先新建一个 .gitignore 文件，避免把不该提交的文件放进仓库。

# Python 缓存
__pycache__/
*.pyc

# 虚拟环境
venv/
.env

# GIS 临时文件
*.lock
*.tmp
*.aux.xml
*.ovr

# 大型数据文件按需排除
*.tif
*.tiff
*.img
*.gpkg
*.shp
*.dbf
*.shx
*.prj

# 系统文件
.DS_Store
Thumbs.db

注意：是否排除 .shp、.gpkg、.tif 要看项目要求。如果这些是示例小数据，可以保留；如果是大型原始数据，建议不要直接放进 Git 仓库。

第二招：提交一个清晰的版本

把需要保存的文件加入暂存区：

git add README.md scripts/ config/

如果你确定当前目录下的文件都应该加入，也可以使用：

git add .

然后提交版本：

git commit -m "初始化 GIS 项目代码结构"

提交说明不要写成“修改”“更新”“测试”这种模糊词。建议使用“动作 + 对象 + 目的”的格式，例如：

• 新增批量裁剪栅格脚本
• 修复 GeoJSON 坐标顺序错误
• 调整 WebGIS 图层配置读取方式
• 补充 PostGIS 建库说明

查看提交历史：

git log --oneline

如果以后代码改坏了，提交历史就是你定位问题的时间线。

第三招：使用分支处理实验性修改

GIS 项目经常需要尝试新算法、新样式或新接口。例如你想把原来的 Shapefile 处理流程改成 GeoPackage 处理流程，但不确定是否稳定。这时不要直接在主分支上乱改，应该创建分支。

git branch gpkg-workflow
git checkout gpkg-workflow

也可以用一条命令创建并切换：

git checkout -b gpkg-workflow

在新分支上修改代码、测试流程、提交记录：

git add .
git commit -m "尝试使用 GeoPackage 重构数据处理流程"

如果测试成功，可以切回主分支并合并：

git checkout main
git merge gpkg-workflow

如果测试失败，也不会影响主分支原来稳定的代码。对于 WebGIS 项目，分支尤其适合处理地图样式调整、图层加载策略优化、接口重构等修改。

第四招：推送到 Gitee 远程仓库

本地 Git 只能保护你当前电脑里的项目。如果硬盘损坏、系统重装或多人协作，就需要远程仓库。Gitee 是国内常用的代码托管平台，访问速度和中文界面对很多 GIS 初学者比较友好。

Gitee 官网基本操作流程如下：

1. 打开 Gitee 官网并登录账号。
2. 点击新建仓库。
3. 填写仓库名称，例如 gis-analysis-demo。
4. 选择是否公开。课程作业和内部项目建议设为私有。
5. 不要重复初始化 README，避免和本地仓库产生不必要冲突。
6. 创建仓库后，复制仓库地址。

把本地仓库关联到 Gitee：

git remote add origin https://gitee.com/你的用户名/gis-analysis-demo.git

推送主分支：

git branch -M main
git push -u origin main

以后每次本地提交后，只需要执行：

git push

如果多人协作，别人已经先提交了新代码，你需要先拉取：

git pull

再处理冲突并推送自己的修改。

常见坑：GIS 项目用 Git 最容易踩的几个问题

常见坑：Git 入门不难，难的是在 GIS 项目中养成正确习惯。下面这些问题很常见。

坑一：把大型空间数据直接提交到 Git

遥感影像、DEM、倾斜摄影、完整行政区划数据、POI 大表等文件往往很大。把这些文件直接放进 Git，会导致仓库变慢，克隆困难，甚至超出平台限制。

更推荐的做法是：

• 代码、配置、SQL、说明文档放进 Git。
• 大型原始数据放在网盘、对象存储、数据服务器或专门的数据目录。
• 在 README 中写清楚数据来源、下载地址、文件路径和处理步骤。
• 只提交小型样例数据，方便别人复现流程。

坑二：没有写 .gitignore

很多 GIS 软件会生成临时文件或辅助文件。Python 也会生成缓存目录。如果不设置 .gitignore，仓库会混入大量无意义文件。

建议项目开始时就创建 .gitignore，并根据实际工具调整。QGIS、ArcGIS Pro、Python、Node.js、PostgreSQL 项目都可能需要不同的忽略规则。

坑三：提交说明太随意

“更新一下”“改了点东西”这种提交说明，在项目初期看起来没问题，但一个月后基本无法追踪问题。

GIS 项目建议把提交说明写得具体一点，例如：

• 修复 EPSG:4326 面积计算不准的问题。
• 新增 PostGIS 空间索引创建脚本。
• 调整 OpenLayers 图层显示顺序。
• 补充 QGIS 模型构建器操作步骤。

坑四：在主分支直接做高风险修改

如果你要重构数据处理流程、替换地图底图、修改数据库结构，最好先开分支。主分支应该尽量保持可运行、可交付。

坑五：把账号密码提交到仓库

数据库连接字符串、地图服务 token、云服务密钥不要提交到 Git。尤其是公开仓库，一旦泄露可能造成数据安全问题。

推荐做法是把敏感配置放到 .env 文件中，并在 .gitignore 里排除：

.env
config.local.json

同时提供一个示例配置文件：

config.example.json

让协作者根据示例自行填写本地配置。

方法比较：Git、Gitee、网盘和压缩包到底怎么选

方法比较：很多 GIS 初学者会问：我已经有网盘和压缩包了，为什么还要用 Git？它们解决的问题不一样。

方式	适合内容	优点	不足
Git	代码、脚本、配置、文档、SQL	可追踪修改、可回退、适合协作	不适合直接管理超大空间数据
Gitee	远程代码仓库、团队协作	中文界面、便于备份和多人开发	仍需理解 Git 基本概念
网盘	大型数据、影像、成果包	适合存放大文件，分享方便	不擅长记录代码细粒度修改
压缩包	阶段性交付成果	简单直观，便于归档	难以合并修改，版本追踪差

推荐组合是：Git 管代码，Gitee 做远程协作，大数据放网盘或数据服务器，最终成果再打包归档。这样既能保持代码历史清晰，也不会让仓库被大型 GIS 数据拖慢。

检查清单：提交 GIS 项目前先检查这 10 项

检查清单：每次提交或推送 GIS 项目前，建议快速检查下面这些项目。

• 是否只提交了必要的代码、配置、SQL 和文档？
• 是否误提交了大型影像、临时文件、缓存文件？
• .gitignore 是否已经覆盖当前项目的临时文件？
• 提交说明是否能说明本次修改的具体目的？
• 主分支上的代码是否可以正常运行？
• 实验性修改是否放在独立分支中？
• README 是否说明了项目运行环境和数据来源？
• 数据库密码、服务 token、密钥是否被排除？
• 推送到 Gitee 前是否先执行过本地测试？
• 多人协作时，推送前是否先拉取了远程最新代码？

对于 GIS 项目，README 至少应该写清楚：

• 项目用途。
• 运行环境，例如 Python 版本、QGIS 版本、数据库类型。
• 目录结构。
• 数据来源和存放方式。
• 主要运行命令。
• 常见问题和注意事项。

FAQ：GIS 项目 Git 入门常见问题

FAQ：下面整理一些 GIS 读者在使用 Git 和 Gitee 时经常遇到的问题。

1. Shapefile 能不能放进 Git？

可以，但要谨慎。Shapefile 不是单个文件，而是一组文件，通常包括 .shp、.shx、.dbf、.prj 等。如果只是很小的样例数据，可以提交；如果是正式生产数据或大型数据，不建议直接放进 Git。

2. GeoPackage 比 Shapefile 更适合放进 Git 吗？

GeoPackage 是单文件格式，管理上比 Shapefile 更方便。但它仍然可能很大，而且二进制文件不适合做文本差异比较。小型示例可以放，核心数据仍建议单独管理。

3. ArcGIS Pro 工程文件要不要全部提交？

ArcGIS Pro 项目文件中可能包含工程配置、数据库连接和缓存内容。建议只提交必要的脚本、工具箱、说明文档和可复现的配置。对于自动生成文件和本地路径强相关的内容，要先测试协作者能否正常打开。

4. QGIS 项目文件可以提交到 Git 吗？

QGIS 的 .qgz 或 .qgs 项目文件可以提交，尤其适合保存图层样式、符号化和布局设置。但要注意图层路径问题，建议使用相对路径，并在 README 中说明数据目录结构。

5. Gitee 上的仓库应该公开还是私有？

课程演示、开源教程和不含敏感数据的示例项目可以公开。包含客户数据、内部业务逻辑、数据库连接信息或未授权数据的项目必须设为私有，并控制成员权限。

6. 已经把密码提交到 Gitee 了怎么办？

第一步不是只删除文件，而是立即更换密码或撤销 token。因为 Git 历史记录里可能仍然存在旧内容。之后再清理提交历史，并检查仓库权限。公开仓库尤其要重视这个问题。

7. Git 冲突是不是很可怕？

冲突只是说明两个人改了同一处内容，Git 无法自动判断保留哪一版。处理冲突时，先明确业务逻辑，再手动保留正确代码。对于 GIS 项目，常见冲突发生在配置文件、前端图层列表、SQL 脚本和 README 中。

8. 不会命令行，能不能用图形界面？

可以。Gitee、Git 客户端和部分 IDE 都提供图形界面。但建议至少掌握 git status、git add、git commit、git push、git pull 这几个命令。遇到问题时，命令行更容易定位原因。

结论：GIS 项目越早使用 Git，后期越省心

结论：GIS 项目代码版本失控，通常不是某一次错误造成的，而是长期缺少版本管理习惯造成的。对于 GIS 学生和初级工程师来说，Git 入门最应该先掌握四件事：初始化仓库、提交清晰版本、用分支做实验、推送到 Gitee 远程仓库。

不要试图一开始就学完 Git 的所有高级命令。先把日常 GIS 项目中的 Python 脚本、WebGIS 页面、PostGIS SQL、QGIS 说明文档管理起来，再逐步学习冲突处理、分支协作和发布流程。只要你能做到每次重要修改都有记录，项目就已经从“靠文件名猜版本”进入了“可追踪、可回退、可协作”的状态。