git

Git

Git Flow

A successful Git branching model

Most used commands

# Configure user information for all local repositories
git config --global user.name "[name]"
git config --global user.email "[email address]"

git clone [url] # Clone from repository
git fetch # Downloads all history from the remote tracking branchesgit pull    # Updates your current local working branch with all new commits from the corresponding remote branch

git init # Init an existing directory into a new Git repository inside the folder you are running this command.
git remote add origin [url] # Specifies the remote repository for your local repository.

git branch [branch-name] # Creates a new branch
git branch -d [branch-name]  #Deletes the specified branch

git add [file] # Snapshots the file in preparation for versioning
git commit -m "[descriptive message]" # Records file snapshots permanently in version history
git log # Lists version history for the current branch
git stash
git stash list/pop/drop
git tag <tag-name>

git push  # Uploads all local branch commits to remote
git push -u [remote-repository] [branch-name] # Publish local branch to remote
git merge [branch]  # Combines the specified branch’s history into the current branch.
git rebase [branch-name] # Rebase the specified branch’s history into the current branch.
git rebase -i HEAD~[n] # Rebase n commits before HEAD
git reset [commit] # Undoes all commits after [commit], preserving changes locally

.gitignore

Sometimes it may be a good idea to exclude files from being tracked with Git. Only source code should be added into the git version control system. This is typically done in a special file named .gitignore. You can find helpful templates for .gitignore files at github.com/github/gitignore.

git worktree

git worktree list
git worktree add <path> <branch>
git worktree prune
git worktree remove

git-lfs

Git Large File Storage is an open source Git extension for versioning large files.

git lfs help [command]  # it will help you check how to use command.

查看 lfs 文件大小

Pull lfs files one-by-one

#!/bin/bash

for dir in observations/*/; do
    echo "Pulling $dir"
    git lfs pull -I "$dir"
done

使用 Git 作为管理工具的软件开发指南

在软件开发的过程中，不可避免的会遇到需要版本管理的场景，Git 就是一种用来为代码类文件做版本管理的软件。尽管除此之外它还有其它作用，不过，本节将专注在介绍那些使用 Git 作为代码管理工具的软件在开发过程中的通用工作流。比如 GitHub 上的各种开源项目，或者某些项目、公司内部的开发项目。本节将要介绍的工作流会以 GitLab 平台为样例，介绍一种最常见、最基础最通用的工作流，在其它平台或工具下也具有类似的流程顺序，只是对应的操作名称、工具有差异。

此外，本指南面向对以下这些要素中的一项或多项有需求的人群，如果这些要素全都不在你的需求范围内，那么你不是本指南的受众：代码管理、版本管理、代码协作、软件开发、Git、开发流程、项目维护。

前置知识

本指南需要你具备一些前置知识，完成一些基本操作。

最好能了解一些概念，如果不了解也影响不是很大：

Git的常见操作

初始化

获取已经存在的仓库

基本配置

作出改动

查阅信息

工作流

一个完整且理想的大型仓库的 git graph 是这样的：

../../assets/images/git_graph_full.png
这张图片意味着：

在大多数中小型项目中，是几乎用不到这样完整的开发流的，一般，上述模型会被简化为只有两个主要部份：

two_branch_graph.png
那么开发时对每个分支的定义将变为：（不要关注branch的名字，关注它的作用，在不同组织、机构、公司命名可能有各自的习惯，但是作用是基本相同的。）

Developer 视角

本小节从 developer 的视角，阐述如果你想加入某个项目的开发，最基本的工作流是什么样子的。

  1. Clone 源码至本地
    使用git clone 将需要开发的代码拉取到本地。然后配置自己的git个人信息。
  2. 在新分支中开发
    先使用git switch切换到你想要开发的分支上，一般来说这个分支是master。然后使用git checkout -b <new-branch-name>从你想开发的分支上创建一个新的分支出来，记得满足项目所需的分支名命名规则。
  3. 进行改动并测试
    在这个分支上完成一些独立且完整的功能开发，开发完成后进行测试。
    请记得遵守自己开发语言的 coding style 以及其它可能的代码规范.
  4. 提交更改
    将每个完整独立的功能使用一个 commit 提交。如果在开发过程中混杂了一些临时的 commit，请使用 git rebase整理自己的提交记录，确保每个 commit 完整且独立，并且使用了#良好的 commit message或遵守项目的 commit message 要求。
    此外，对于具体的项目，可能还需要更新#CHANGELOG、文档或者其它文件。
  5. 推送到远端
    使用git push将开发完成的代码推送到远端。
    提出 Merge Request 或 Pull Request 之前，一般需要确保分支已经 rebase 至目标分支的最新情况，来保持线性的开发历史。
  6. 提出 Merge Request 或 Pull Request
    在对应的代码平台上，提交MR或者PR。按照项目的要求填写清楚信息，选择好项目指定的 tag。将reviewer修改为仓库指定的人选或者maintainer。如果MR已经准备完成，assign项目要求的人员或者maintainer；如果尚未完全准备好被review，assign你自己。
  7. 等待服务器的自动化检查流程运行完毕，如果某些必要的自动化检查未通过，请按照未通过的原因修改自己的代码。重复2-4步直至可以动过全部必要的自动化检查。
    一般这些自动化检查会显示为一个红色或绿色的标识状态的图标。可能会叫做CI/CD，pipeline，action等。
  8. 等待 reviewer 给出反馈，如果有需要改动的地方，根据意见重复2-4步，改动完成后回复提出意见的人，清楚地表明已经完成修改，直至reviewer认为没有问题。
  9. 等待PR或MR被合并。一次单一的开发就完成了。
  10. 继续使用项目，在发现有问题时，提交详细的问题描述至 issue 区。或者继续完成maintainer指派给你的开发任务。

Maintainer 视角

本小节从 maintainer 的视角，阐述如果你成为某个项目的 maintainer， 需要做好什么才能维护项目的工作流。

  1. 确保你维护的项目已经为开发者提供了明确的指南，来指引正确地他们向你维护的项目提交符合你内心要求的代码。
  2. 为你的项目设置必要的自动化检查流程。
    对于普通的提交，这些自动化检查可能会包括：对代码的静态检查，对文本、代码的格式、拼写检查，对某些代码的可编译性检查，对有需求的信息提供与否的检查，代码的测试、分支内容是否最新。
    对于合并后、打上tag的提交，这些自动化流程可能会包括：自动关闭有关联的 issue 或其它外部平台的资源，自动发布有关代码或构建后的产物至需要的目的地，自动更新某些描述、文档、运行中软件的版本等。
  3. 等待新接收到的PR或MR所有自动化检查通过。
  4. 对需要 review 的代码分配合理的 reviewer （小型项目一般就是你自己），让他检查所有需要人工检查的内容。比如：此问题的解决是否必要，目标分支是否正确，代码实现是否正确高效，是否提供了必要的注释或说明 ，是否出现了不应当出现的文本内容（有侮辱性的词汇，有风险的实现等）。
    检查后需要指引开发者完成有关修复，直至没有问题。
  5. 合并分支至目标分支 。合并时可能需要注意：是否需要将本次 MR 或 PR 中所有的 commit 都合并成一个 commit 再合并，是否需要产生一个merge commit，是否需要自动将分支 rebase 至最新。
  6. 及时根据项目情况，更新：
    1. 开发指南和有关文档
    2. 关闭已解决、不需要解决的 issue
    3. 为 issue 分配合适的开发者
    4. 检查 MR 或 PR 的进展
    5. 配置必要的自动检查流程

通用开发规范

以下是一些常见的、通用的开发规范，在具体项目中可能会有不同的具体要求，需要以具体项目的要求为准。但是在你自己创建项目时，或者项目还没有规则时，使用这些规则是一个不错的开始。

良好的 commit message

commit message 必须简短明确，不要夹杂语义不明或重复性、含糊性的表述。请参考以下链接。

https://wiki.openstack.org/wiki/GitCommitMessages#Information_in_commit_messages

当然，在某些项目中 commit message 可能还需要满足某些格式要求，以规范形式，或者使得某种自动化工具可以自动从中提取信息，具体情况应当按照具体项目的要求进行。

分支

用不同的前缀来命名不同的分支，常见的分支前缀如下:

在部分项目中，可能还需要在前缀中添加开发者姓名或开发子项目或子模块的名称：

版本控制

为了了解和标识软件的开发进展，有时候我们为代码打上 tag，标识当前的软件版本，版本的定义需遵循如下的规则： Semantic Versioning 2.0.0

CHANGELOG

Changelog 用来记录代码变更的情况，它的使用 遵循： Keep A Changelog 1.0.0

常见问题

其它有关需求传送门

如果本文中的内容你已全部理解掌握，仍然不能满足你的开发需求，那么说明你应该已经是一名具有搜索和学习能力的开发者了。这里提供了一些常见的进阶需求可能的技术方案或工具，你可以根据提供的链接或关键词自行搜索有关的资料。