目录
- [从零配置一个规范的 Python Git 仓库（适用于 Gitee / GitHub）](#从零配置一个规范的 Python Git 仓库（适用于 Gitee / GitHub）)
从零配置一个规范的 Python Git 仓库（适用于 Gitee / GitHub）
在学习 Python 的过程中，我们常常希望把自己的练习代码托管到 Gitee 或 GitHub 上。
本文将一步步教你如何从零创建一个 规范、干净、可长期维护 的 Python 仓库。
本文环境为 Windows 11 + PyCharm Community Edition 2024.3.4。
一、仓库用途说明
本文场景：
- 仓库供个人学习使用；
- 仓库中会包含多个 Python 项目；
- 不在乎他人如何使用代码，因此选择 MIT-0 开源协议。
二、仓库初始化流程
-
在 Gitee 或 GitHub 创建一个空仓库
- 仓库名示例：
python-learn - 选择开源协议：MIT-0 License(视情况选择最合适的)
- 其他选项保持默认。
- 仓库名示例：
-
在本地克隆仓库
bashgit clone git@gitee.com:用户名/python-learn.git cd python-learn -
配置
.gitignore在仓库根目录下新建
.gitignore文件，内容如下：gitignore# 忽略Python编译生成的临时文件 __pycache__/ *.py[cod] *$py.class # 忽略虚拟环境 .venv/ venv/ env/ ENV/ # 忽略构建产物 build/ dist/ *.egg-info/ .eggs/ # 忽略测试缓存 .pytest_cache/ .tox/ .nox/ .coverage coverage.xml # 忽略Jupyter与IDE文件 .ipynb_checkpoints/ .idea/ .vscode/ .ropeproject/ # 忽略系统文件 Thumbs.db .DS_Store说明：
- 该版本
.gitignore兼容多个 Python 项目； - 适合个人学习、无外部依赖的仓库；
- 自动避免上传虚拟环境与缓存文件。
- 该版本
下面提供了一份更加详细的版本，由于文件类型众多，请检查是否符合自己后再使用
bash
# ========================
# Python 常规 & byte-compiled
# ========================
__pycache__/
*.py[cod]
*$py.class
*.pyo
*.pyd
# C extensions
*.so
# ========================
# Distribution / packaging / build
# ========================
.Python
build/
dist/
develop-eggs/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
pip-wheel-metadata/
*.manifest
*.spec
# ========================
# Installer / pip logs
# ========================
pip-log.txt
pip-delete-this-directory.txt
# ========================
# Unit test / coverage / CI
# ========================
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/
# ========================
# Virtual environments (common names)
# ========================
venv/
env/
ENV/
.venv/
.ENV/
.venvs/
venv.bak/
virtualenv/
venv3/
.env/
.envrc
venv*/ # 额外保险：匹配 venv1 venv_project 等
# ========================
# PyCharm / JetBrains
# ========================
# 忽略整个 .idea（个人 IDE 设置）
.idea/
# 如果你想共享 run configs 等，可改为只忽略 workspace 文件：
# .idea/workspace.xml
# .idea/tasks.xml
# .idea/usage.statistics.xml
# .idea/dictionaries/
# ========================
# Other editors / IDEs
# ========================
.vscode/
*.sublime-workspace
*.sublime-project
# ========================
# Jupyter / IPython
# ========================
.ipynb_checkpoints
*.ipynb_checkpoints
profile_default/
ipython_config.py
# ========================
# Notebook / Data files (按需取消注释某些数据文件)
# ========================
# 如果你不想提交大型数据集或本地数据库：
# *.sqlite3
# *.db
# *.db-journal
# ========================
# Logs, temp, caches
# ========================
*.log
*.tmp
*.temp
tmp/
temp/
.cache/
.mypy_cache/
.python-eggs/
*.swp
*.swo
.idea/.name # 避免某些系统留下的小文件
# ========================
# OS generated
# ========================
.DS_Store
Thumbs.db
desktop.ini
# ========================
# Packaging / archives
# ========================
*.zip
*.tar.gz
*.rar
# ========================
# Tool-specific / lesser-used
# ========================
# pyenv
.python-version
# pipenv (如果你希望忽略 Pipfile.lock 请取消注释)
# Pipfile.lock
__pypackages__/
celerybeat-schedule
celerybeat.pid
*.sage.py
.pybuilder/
target/
.mypy_cache/
.dmypy.json
dmypy.json
.pyre/
.pytype/
cython_debug/
# ========================
# Optional: 私有/凭证（请按需启用）
# ========================
# secrets/
# credentials.json
# local_settings.py三、配置 .gitattributes
在根目录新建 .gitattributes 文件，用于统一换行符和文本编码：
gitattributes
# 统一文本文件的换行符为LF，保持跨平台一致
* text=auto
# 强制UTF-8编码识别
*.py text eol=lf working-tree-encoding=UTF-8
*.md text eol=lf working-tree-encoding=UTF-8
*.txt text eol=lf working-tree-encoding=UTF-8
*.gitignore text eol=lf working-tree-encoding=UTF-8
*.gitattributes text eol=lf working-tree-encoding=UTF-8解释：
- Windows 默认是 CRLF，Linux/macOS 是 LF；
- 该配置确保仓库内统一为 LF，避免多人协作或跨平台时的换行符冲突；
- PyCharm、VSCode 均能正确识别 UTF-8。
下面提供了一份更加详细的版本，由于文件类型众多，请检查是否符合自己后再使用
bash
# ================================
# 行尾规范：统一使用 LF
# ================================
* text=auto eol=lf
# Python 源码与脚本文件始终使用 LF
*.py text eol=lf
*.pyw text eol=lf
# 配置类文本文件（保持 LF）
*.txt text eol=lf
*.md text eol=lf
*.json text eol=lf
*.yml text eol=lf
*.yaml text eol=lf
*.ini text eol=lf
*.toml text eol=lf
*.cfg text eol=lf
*.csv text eol=lf
# Shell / Batch / PowerShell
*.sh text eol=lf
*.bash text eol=lf
*.bat text eol=crlf
*.cmd text eol=crlf
*.ps1 text eol=crlf
# Web / 前端相关文件
*.html text eol=lf
*.css text eol=lf
*.js text eol=lf
# 项目配置与说明文件
*.gitignore text eol=lf
*.gitattributes text eol=lf
LICENSE text eol=lf
# 二进制文件（不要转行）
*.jpg binary
*.jpeg binary
*.png binary
*.gif binary
*.ico binary
*.pdf binary
*.exe binary
*.dll binary
*.pyd binary
*.zip binary
*.tar.gz binary
*.rar binary
*.7z binary
*.mp4 binary
*.mp3 binary
*.avi binary
*.mov binary
*.ttf binary
*.otf binary
# Jupyter Notebook
*.ipynb text eol=lf四、编写 README.md
示例内容如下：
markdown
# Test
#### 介绍
介绍仓库内容
#### 软件架构
软件架构说明
#### 安装教程
1. xxxx
2. xxxx
3. xxxx
#### 使用说明
1. xxxx
2. xxxx
3. xxxx
#### 参与贡献
1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request五、首次提交与推送
执行以下命令完成配置文件的首次提交：
bash
git add .gitignore .gitattributes README.md
git commit -m "Add initial Python repository configuration"
git push随后即可在仓库中添加你的第一个学习项目，例如：
bash
git add Project/
git commit -m "Add a project"
git push六、关于 CRLF / LF 的提示说明
Windows 用户在提交时可能会看到如下提示：
warning: CRLF will be replaced by LF the next time Git touches it这是 正常现象 。
Git 会在存储时统一为 LF，但在你本地编辑时仍保留 CRLF，不影响任何功能或执行。
七、后续提交新项目的标准流程
| 步骤 | 命令 | 说明 |
|---|---|---|
| 1️⃣ | git status |
查看当前仓库状态 |
| 2️⃣ | git add . |
暂存所有新文件 |
| 3️⃣ | git commit -m "描述这次提交的内容" |
提交到本地版本库 |
| 4️⃣ | git push |
推送到远程仓库 |
建议每个项目放在独立的文件夹中（如 Project1/、Project2/ 等）。
八、总结
至此，你已经拥有一个：
- ✅ 结构清晰
- ✅ 文件规范
- ✅ 支持多个项目
- ✅ 自动处理换行与编码问题
的 Python 代码仓库 。
你可以长期使用该模板来创建新的仓库，完全不用担心跨系统、编码或文件冗余问题。
九、免责声明
本文仅为学习与经验分享，所有操作均在个人环境中验证通过。
如读者在实际使用中修改配置文件、路径或命令而导致问题，作者概不负责 。
建议在每次修改配置文件前备份项目文件。
封面图来源于网络，如有侵权，请联系删除！