您已经有了自己的 NumPy 存储库,通过以下方式 创建NumPy fork , 制作本地副本 ,您已配置 git 通过以下 Git配置 ,并已链接上游存储库,如中所述 Linking your repository to the upstream repo .
下面描述的是一个推荐的Git工作流。
简而言之:
开始新的 特征分支 对于您所做的每一组编辑。见 below .
砍掉!见 below
完成后:
贡献者 :将您的功能分支推到您自己的Github回购,以及 create a pull request .
核心开发者 :如果要在不进行进一步检查的情况下推动更改,请参阅注释 below .
这种工作方式有助于保持工作的良好组织和历史尽可能清楚。
参见
有很多在线教程可以帮助您 learn git . 有关特定Git工作流的讨论,请参见 linux git workflow 和 ipython git workflow .
首先,从 upstream 储存库:
upstream
git fetch upstream
然后,基于上游存储库的主分支创建一个新分支:
git checkout -b my-new-feature upstream/master
# hack hack git status # Optional git diff # Optional git add modified_file git commit # push the branch to your own Github repo git push origin my-new-feature
做些改变。当你觉得你已经做了一套完整的、可工作的相关更改时,继续下一步。
可选:检查更改了哪些文件 git status (见 git status )您将看到这样一个列表:
git status
# On branch my-new-feature # Changed but not updated: # (use "git add <file>..." to update what will be committed) # (use "git checkout -- <file>..." to discard changes in working directory) # # modified: README # # Untracked files: # (use "git add <file>..." to include in what will be committed) # # INSTALL no changes added to commit (use "git add" and/or "git commit -a")
可选:将更改与使用 git diff (git diff )这将显示一个简单的文本浏览器界面,突出显示文件与以前版本之间的差异。
git diff
使用添加任何相关的修改或新文件 git add modified_file (见 git add )这会将文件放入临时区域,该区域是将添加到下一次提交的文件队列。仅添加具有相关、完整更改的文件。保留未完成更改的文件供以后提交。
git add modified_file
要将分段文件提交到回购的本地副本中,请执行以下操作: git commit . 此时,将打开一个文本编辑器,允许您编写提交消息。阅读 commit message section 以确保您正在编写一个格式正确且足够详细的提交消息。保存消息并关闭编辑器后,将保存提交。对于普通提交,可以使用 -m 旗帜。例如, git commit -am "ENH: Some message" .
git commit
-m
git commit -am "ENH: Some message"
在某些情况下,您将看到commit命令的这种形式: git commit -a . 额外的 -a 标记自动提交所有修改的文件并删除所有删除的文件。这可以为您节省大量的输入 git add 命令;但是,如果不小心,它可以向提交添加不需要的更改。有关详细信息,请参阅 why the -a flag? -以及 tangled working copy problem .
git commit -a
-a
git add
将更改推到Github上的复刻回购:
git push origin my-new-feature
有关详细信息,请参阅 git push .
注解
假设您遵循了这些页面中的说明,Git将创建一个默认链接,指向 github 回购称为回购 origin . 在git>=1.7中,可以使用 --set-upstream 选项:
origin
--set-upstream
git push --set-upstream origin my-new-feature
从今以后 git 会知道 my-new-feature 与 my-new-feature 你自己的分支 github 回购协议。随后的推送调用将简化为以下内容:
my-new-feature
git push
你必须使用 --set-upstream 为您创建的每个新分支。
可能是在您进行编辑时,新提交已添加到 upstream 影响你的工作。在这种情况下,请按照 在主服务器上重新平衡 将这些更改应用于您的分支机构。
提交消息应该是清晰的,并且遵循一些基本规则。例子::
ENH: add functionality X to numpy.<submodule>. The first line of the commit message starts with a capitalized acronym (options listed below) indicating what type of commit this is. Then a blank line, then more text if needed. Lines shouldn't be longer than 72 characters. If the commit is related to a ticket, indicate that with "See #3456", "See ticket 3456", "Closes #3456" or similar.
描述变更的动机、bug修复的性质或关于增强功能的一些细节,也可以将其包含在提交消息中。消息应该是可以理解的,而不需要考虑代码的变化。像这样的提交消息 MAINT: fixed another one 是不该做的事情的一个例子;读者必须到别处寻找上下文。
MAINT: fixed another one
启动提交消息的标准首字母缩写为:
API: an (incompatible) API change BENCH: changes to the benchmark suite BLD: change related to building numpy BUG: bug fix DEP: deprecate something, or remove a deprecated object DEV: development tool or utility DOC: documentation ENH: enhancement MAINT: maintenance commit (refactoring, typos, etc.) REV: revert an earlier commit STY: style fix (whitespace, PEP8) TST: addition or modification of tests REL: related to releasing numpy
如果你计划一个新的特性或者API的改变,最好先发邮件给NumPy mailing list 征求意见。如果你一个星期都没有回音,那就可以再次点击列表。
当你觉得你的工作已经完成时,你可以创建一个拉请求(pr)。Github有一个很好的帮助页面,概述了 filing pull requests .
如果您的更改涉及对API的修改或对函数的添加/修改,请在 doc/release/upcoming_changes/ 目录中的说明和格式 doc/release/upcoming_changes/README.rst 文件。
doc/release/upcoming_changes/
doc/release/upcoming_changes/README.rst
我们会尽快审查pull请求,通常是在一周内。如果您在两周内没有收到任何评论,可以通过在您的PR上添加评论(这将通知维护人员)来请求反馈。
如果你的公关是大型或复杂的,要求输入的numpy讨论邮件列表也可能是有用的。
这将使用上游的更改更新您的功能分支 NumPy github 回购协议。如果你完全不需要这样做,尽量避免这样做,除非你完成了。第一步是使用上游的新提交更新远程存储库:
接下来,您需要更新功能分支:
# go to the feature branch git checkout my-new-feature # make a backup in case you mess up git branch tmp my-new-feature # rebase on upstream master branch git rebase upstream/master
如果对同样在上游更改的文件进行了更改,则可能会生成需要解决的合并冲突。见 below 在这种情况下寻求帮助。
最后,在成功的重新设置后删除备份分支:
git branch -D tmp
在master上重新定位比在上游合并回分支更可取。使用 git merge 和 git pull 在处理功能分支时不鼓励。
git merge
git pull
有时,你会把合并或再平衡搞砸。幸运的是,在Git中,从这些错误中恢复是相对简单的。
如果你在一段时间内搞砸了:
git rebase --abort
如果你注意到你在钢筋网后面搞砸了:
# reset branch back to the saved point git reset --hard tmp
如果您忘记创建备份分支:
# look at the reflog of the branch git reflog show my-feature-branch 8630830 my-feature-branch@{0}: commit: BUG: io: close file handles immediately 278dd2a my-feature-branch@{1}: rebase finished: refs/heads/my-feature-branch onto 11ee694744f2552d 26aa21a my-feature-branch@{2}: commit: BUG: lib: make seek_gzip_factory not leak gzip obj ... # reset the branch to where it was before the botched rebase git reset --hard my-feature-branch@{2}
如果你没有把事情搞砸,但是有合并冲突,你需要解决这些冲突。这可能是更棘手的事情之一。有关如何执行此操作的详细说明,请参见 this article on merging conflicts .
只为您自己的功能分支执行此操作。
你做出的承诺中有一个令人尴尬的拼写错误?或者,也许你做了一些错误的开始,你希望后人不要看到。
这可以通过 交互式再平衡 .
假设提交历史记录如下所示:
git log --oneline eadc391 Fix some remaining bugs a815645 Modify it so that it works 2dec1ac Fix a few bugs + disable 13d7934 First implementation 6ad92e5 * masked is now an instance of a new object, MaskedConstant 29001ed Add pre-nep for a couple of structured_array_extensions. ...
和 6ad92e5 最后一次提交是在 master 分支机构。假设我们要进行以下更改:
6ad92e5
master
为重写提交消息 13d7934 为了更明智的事情。
13d7934
结合承诺 2dec1ac , a815645 , eadc391 变成一个。
2dec1ac
a815645
eadc391
我们的做法如下:
# make a backup of the current state git branch tmp HEAD # interactive rebase git rebase -i 6ad92e5
这将打开一个编辑器,其中包含以下文本:
pick 13d7934 First implementation pick 2dec1ac Fix a few bugs + disable pick a815645 Modify it so that it works pick eadc391 Fix some remaining bugs # Rebase 6ad92e5..eadc391 onto 6ad92e5 # # Commands: # p, pick = use commit # r, reword = use commit, but edit the commit message # e, edit = use commit, but stop for amending # s, squash = use commit, but meld into previous commit # f, fixup = like "squash", but discard this commit's log message # # If you remove a line here THAT COMMIT WILL BE LOST. # However, if you remove everything, the rebase will be aborted. #
为了实现我们想要的,我们将对其进行以下更改:
r 13d7934 First implementation pick 2dec1ac Fix a few bugs + disable f a815645 Modify it so that it works f eadc391 Fix some remaining bugs
这意味着(i)我们要编辑的提交消息 13d7934 和(ii)将最后三个提交折叠成一个。现在我们保存并退出编辑器。
然后Git会立即打开一个编辑器来编辑提交消息。修改后得到输出:
[detached HEAD 721fc64] FOO: First implementation 2 files changed, 199 insertions(+), 66 deletions(-) [detached HEAD 0f22701] Fix a few bugs + disable 1 files changed, 79 insertions(+), 61 deletions(-) Successfully rebased and updated refs/heads/my-feature-branch.
历史看起来是这样的:
0f22701 Fix a few bugs + disable 721fc64 ENH: Sophisticated feature 6ad92e5 * masked is now an instance of a new object, MaskedConstant
如果它出了问题,恢复是可能的,正如解释的那样。 above .
git checkout master # delete branch locally git branch -D my-unwanted-branch # delete branch on github git push origin --delete my-unwanted-branch
另请参见:https://stackoverflow.com/questions/2003505/how-do-i-delete-a-git-branch-locally-and-remotely
如果您想与其他人一起处理一些事情,在这些事情中,您都要提交到同一个存储库,甚至是同一个分支,那么只需通过 github.
第一把叉子拧进你的帐户,从 创建NumPy fork .
然后,转到您的复刻存储库Github页面,说 https://github.com/your-user-name/numpy
https://github.com/your-user-name/numpy
单击“管理”按钮,将其他任何人作为合作者添加到回购协议中:
现在所有这些人都能做到:
git clone git@github.com:your-user-name/numpy.git
记住,链接以 git@ 使用ssh协议并读写;链接以 git:// 是只读的。
git@
git://
然后,您的合作者可以按照通常的方式直接提交到回购协议中:
git commit -am 'ENH - much better code' git push origin my-feature-branch # pushes directly into your repo
要查看存储库分支和提交的图形表示,请执行以下操作:
gitk --all
要查看此分支的线性提交列表,请执行以下操作:
git log
你也可以看看 network graph visualizer 为了你 github 回购协议。
backporting是复制在中提交的新功能/修复程序的过程。 numpy/master 回到稳定释放分支。要做到这一点,你需要从你要反向移植的分支上创建一个分支,Cherry选择你想要的提交。 numpy/master ,然后提交包含该端口的分支的请求。
numpy/master
首先,你需要建立你将要工作的分支。这需要基于旧版本的numpy(而不是master)::
# Make a new branch based on numpy/maintenance/1.8.x, # backport-3324 is our new name for the branch. git checkout -b backport-3324 upstream/maintenance/1.8.x
现在,您需要使用 git cherry-pick ::
# Update remote git fetch upstream # Check the commit log for commits to cherry pick git log upstream/master # This pull request included commits aa7a047 to c098283 (inclusive) # so you use the .. syntax (for a range of commits), the ^ makes the # range inclusive. git cherry-pick aa7a047^..c098283 ... # Fix any conflicts, then if needed: git cherry-pick --continue
你可能会在这里遇到一些冲突。这些问题的解决方法与合并/重新平衡冲突相同。除了这里你可以用 git blame 查看主分支和后端口分支之间的区别,以确保没有任何事情出错。
将新分支推送到Github存储库:
git push -u origin backport-3324
最后使用Github发出请求。确保它是针对维护分支而不是主服务器的,Github通常会建议您对主服务器提出请求。
需要对主NumPy回购的提交权限。
当您在一个功能分支中有一组“准备就绪”的更改准备好进行numpy时 master 或 maintenance 树枝,你可以把它们推到 upstream 如下:
maintenance
首先,在目标分支上合并或重新设置基。
只有少数不相关的提交才喜欢重新平衡:
git fetch upstream git rebase upstream/master
见 在主服务器上重新平衡 .
如果所有提交都相关,请创建合并提交::
git fetch upstream git merge --no-ff upstream/master
检查你要推的东西看起来是否合理:
git log -p upstream/master.. git log --oneline --graph
向上游推:
git push upstream my-feature-branch:master
通常使用 -n 旗到 git push 首先检查是否要将所需更改推送到所需的位置。
-n