Markdown Git 分支 开源协议

第5章 开发文档与版本控制

先掌握 Markdown——用纯文本写出清晰的技术文档;再学习 Git——用版本控制管理每一次变更;最后认识软件许可证,让开源协作有法可依。

本章知识地图
一条主线:用 Markdown 写文档 → 用 Git 管版本 → 用许可证定规则
Markdown 文档
纯文本 · 语法 · 最佳实践
版本控制 Git
仓库 · 分支 · 合并
软件许可证
GPL · MIT · Apache
01

Markdown 编写开发文档

Markdown 是一种用简单语法代替复杂排版的标记语言——专注内容创作,而无需分心调整格式。

Markdown 的基本特征2004 年诞生 · 易读易写

诞生背景 2004 年由 John Gruber 创建,目标实现「易读易写」的纯文本格式;核心哲学:内容与呈现分离
基本特点 扩展名 .md / .markdown;兼容所有文本编辑器;被 GitHub、知乎、简书等平台原生支持。
生态地位 GitHub / Gitee 的 README 标准格式;技术文档首选;代码与文档混合编写时尤其高效。
标准体系说明
CommonMark标准化的 Markdown 版本,统一语法行为,是「通用地基」
GFMGitHub Flavored Markdown,增加表格、任务列表、删除线等
扩展语法各平台定制(如 Mermaid 图表、公式),需显式标注
注意:Markdown 的核心是「内容与呈现分离」——你只负责结构和内容,渲染交给工具;写文档时不要纠结字号、颜色。

核心应用场景Docs as Code

技术文档 项目 README、API 文档(结合 Swagger / MkDocs)、变更日志。
知识笔记 Obsidian / Notion / 语雀 / 飞书;纯文本天然利于 Git 版本控制。
学术与发布 Pandoc 转 PDF / 幻灯片;Hexo / Hugo 静态博客。
企业价值 文档即代码(Docs as Code):与源码同仓、同版本、同流程,协作效率高。

基础语法速查

元素语法示例
标题# 一级 ## 二级 ### 三级
粗体 / 斜体**粗体** *斜体*
无序 / 有序列表- 项目 1. 项目
链接[文字](url)
图片![说明](图片地址)
引用> 引用内容
行内代码 / 代码块`code` ```语言 … ```
任务列表(GFM)- [ ] 待办 - [x] 完成
最佳实践:标题层级不超过 3 级;每行尽量 ≤80 字符(便于 Git diff);列表统一用 -;优先使用 CommonMark 标准语法。
一句话总结:Markdown 用纯文本写结构清晰的文档,内容与呈现分离,天然适合 Git 协作与多格式输出。
本节小结
  • 核心理念:易读易写、内容与呈现分离;扩展名 .md。
  • 标准:CommonMark(基础)+ GFM(表格、任务列表等)。
  • 场景:README、知识笔记、API 文档、博客;Docs as Code。
  • 语法:标题 #、粗斜体、列表、链接、图片、引用、代码块;最佳实践:标题 ≤3 级、行宽适中。
?
课堂练习 · 1 Markdown
1Markdown 的核心理念是(  )。
解析:参考答案:C
Markdown 强调内容与呈现分离:作者专注内容,渲染交给工具。
2下列属于 GFM 特有扩展的是(  )。
解析:参考答案:A
标题、引用、斜体是 CommonMark 基础语法;任务列表是 GFM 扩展。
3Markdown 中插入图片的语法是(  )。
解析:参考答案:C
图片语法 = 链接语法前加感叹号:![说明](地址)。
4关于 Markdown 最佳实践,错误的是(  )。
解析:参考答案:A
最佳实践是每行不超过约 80 字符,便于 Git 逐行 diff 和阅读。
02

版本控制工具 · Git

版本控制记录和管理文件变更,让开发者能追踪历史、并行协作、随时回滚。Git 是当前最流行的分布式版本控制系统。

版本控制的类型本地 → 集中式 → 分布式

特性本地 VCS集中式(SVN)分布式(Git)
数据存储本地中央服务器每人完整副本
是否需网络提交/更新时需要仅同步时需要
单点故障有(服务器)
分支效率高(轻量分支)
典型工具RCSSVN、CVSGit、Mercurial
背景:Git 由 Linux 之父 Linus Torvalds 于 2005 年开发,用于管理 Linux 内核;如今绝大多数开发者使用 Git。

本地仓库与远程仓库

工作区 项目目录,直接编辑的文件;改动不会自动被 Git 记录。
暂存区 中间区域,临时存放准备提交的改动(像「购物车」,可挑选提交)。
.git 版本库 隐藏目录,存储全部历史、分支、提交;支持离线工作,切勿删除。
远程仓库 GitHub / GitLab / Gitee 等云端或局域网仓库,用于备份与团队协作。
基本流程:工作区 git add → 暂存区 git commit → 本地分支 git push → 远程仓库;git clone 复制完整仓库。

分支、合并与冲突

分支 轻量指针,指向某次提交;可并行开发功能而不影响主线。
HEAD 当前所在位置的指针,通常指向分支名;分离头指针状态下新提交易丢失,需 git switch -c 保存。
merge 合并产生双父提交,保留分叉历史;冲突用标记手动解决后 add + commit。
rebase 把提交「重新播放」到新基点,历史变直线、哈希改变;只用于未推送的本地分支。
解决冲突顺序:编辑文件删除冲突标记 → git addgit commit。切勿对已推送的共享分支执行 rebase。

常用命令与工作流

场景命令 / 做法
初始化 / 克隆git init git clone <url>
查看状态与差异git status git diff
暂存与提交git add . git commit -m "说明"
分支git branch git switch -c feat/xxx
同步远程git pull git push
撤销(工作区)git restore file
1个人实践:功能分支(feat/、fix/)→ 频繁小提交 → 完成后开 PR 审查合并。
2企业常见:GitHub Flow(main + 短生命周期功能分支)或 Git Flow(main / develop / feature / release / hotfix)。
3安全习惯:敏感文件用 .gitignore 排除;main 分支受保护,禁止直接推送。
一句话总结:Git 用本地完整副本 + 轻量分支实现离线协作与安全回滚;add → commit → push,冲突手动解决,rebase 仅限本地未推送分支。
本节小结
  • 三类型:本地 / 集中式(SVN)/ 分布式(Git,每人完整副本)。
  • 三区:工作区 → 暂存区 → .git 版本库;远程用于协作与备份。
  • 分支轻量;merge 保留历史,rebase 改写历史(勿用于已推送分支)。
  • 冲突:编辑 → add → commit;工作流以功能分支 + PR 为主。
?
课堂练习 · 2 Git
1集中式版本控制(如 SVN)的主要缺点是(  )。
解析:参考答案:B
集中式所有历史在中央服务器:宕机则无法协作,操作依赖网络。
2Git 属于哪一类版本控制系统(  )。
解析:参考答案:C
Git 是分布式:每人本地都是完整副本,可离线操作。
3解决合并冲突的正确顺序是(  )。
解析:参考答案:B
手动编辑解决冲突 → add 标记已解决 → commit 完成合并。
4关于 Git 工作流,正确的是(  )。
解析:参考答案:C
功能分支 + PR 审查;勿 rebase 已推送分支;敏感信息用 .gitignore 排除。
03

软件许可证协议

软件许可证是用户与版权所有者之间的法律合同,规定使用、修改、分发软件时必须遵守的规则——用别人的代码前,先看许可证。

为什么协议如此重要?

保护开发者 明确版权归属,防止他人盗用并声称是自己的。
约束用户 规定能否修改、闭源、商用,防止滥用。
促进协作 清晰规则降低法律风险,方便社区与企业采用。
规避风险 选错协议可能导致被迫开源或侵权诉讼。

常见开源协议对比

协议宽松程度核心特点典型项目
GPL最严格传染性:衍生作品必须开源Linux、Git
LGPL较严格动态链接可闭源;改库本身须开源部分系统库
Apache 2.0宽松宽松 + 专利授权条款Android、Kubernetes
MIT / BSD最宽松保留版权声明即可,可闭源商用大量前端库、工具
选择口诀:全开放选 MIT/BSD;要专利保护选 Apache;库想被广泛用选 LGPL;强制开源选 GPL;核心资产用商业许可。协议一经指定通常不可随意撤销。

开源 vs 商业闭源

开源协议 可查看、修改、分发源码;部分可商用;强调共享与协作。
商业闭源 获取源码受限,需购买许可;修改与再分发通常被严格限制。
实践提醒:引入第三方库前务必确认许可证是否与项目目标兼容;GPL 对商业闭源产品风险最大。
一句话总结:许可证是使用与分发代码的法律边界——GPL 强制开源、MIT/BSD 几乎零限制、Apache 兼顾宽松与专利保护;选协议前想清楚「希望别人怎么用你的代码」。
本节小结
  • 许可证 = 有法律效力的合同,规定使用 / 修改 / 分发规则。
  • GPL 传染性最强;MIT/BSD 最宽松;Apache 2.0 带专利保护。
  • 开源可看可改可分发;商业闭源需许可且限制多。
  • 选协议前明确目标;引入依赖时检查兼容性。
?
课堂练习 · 3 软件许可证
1软件许可证协议的本质是(  )。
解析:参考答案:A
许可证是法律合同,定义版权所有者与用户的权利与责任。
2GPL 协议最著名的特点是(  )。
解析:参考答案:B
GPL 的 copyleft:衍生作品也必须以 GPL 开源(如 Linux、Git)。
3希望开源且获得专利保护,最合适的是(  )。
解析:参考答案:B
Apache 2.0 提供明确的专利授权条款,适合「开源 + 专利保护」(如 Android)。
4MIT 协议下,用户通常可以(  )。
解析:参考答案:A
MIT 极宽松:保留版权与许可声明即可,私用、商用、修改、闭源均可。

延伸学习资源

先动手试官方文档与交互工具,再深入原理。

CommonMark 规范

commonmark.org

Markdown 官方标准化规范与交互式教程。

Git 官方文档

git-scm.com/doc

官方手册、Pro Git 免费电子书与命令速查。

廖雪峰 Git 教程

liaoxuefeng.com

中文经典入门:从安装配置到分支管理。

Git 在线练习

learngitbranching.js.org

可视化分支练习:merge / rebase / cherry-pick。

GitHub / Gitee

github.com · gitee.com

代码托管与协作:fork、PR、Issues 完整流程。

choosealicense

choosealicense.com

按项目目标推荐合适的开源许可证。

Open Source Initiative

opensource.org

开源定义与 OSI 认证许可证原文。

Gitee 帮助中心

gitee.com/help

国内平台操作指南:仓库、PR、团队协作。

随机提问
点击下方按钮开始
今日已提问:0/0