如何管理你Github上的开源项目

使用 Github 也有很长一段时间了,或多或少都有点自己的经验和心得,虽然说不上一定对,但是很多都是参考一些大佬的博客或者项目学来的,如果有什么问题或者不足的地方也可以和我探讨。

前言

其实突然想写这篇博客的原因,主要是最近看到学弟的开源项目上连基本的 .gitignore 文件都没有,连带着 IDE 的配置文件(.idea/,*.iml 等),out 目录都在上面,所以他们在用 git 协同开发的时候经常会出现冲突。

此外,大部分都没有 README,有的学弟兴致勃勃的开源了自己写的项目,可惜很少有人去 star,其实你换个角度想,这个项目写的好不好,有没有学习价值,除了你知道外,你不用文档的形式展示出来,别人又怎么会去看呢?当然如果你只是用 github 来简单的存储代码,那么当我没说,但我觉得就算留一个只有标题的 README 都比什么都不留好得多。

如果你细心的话,就会发现每次在 Github 上创建项目的时候,都有这么几个选项

  • Repository name 项目名
  • Description 项目描述
  • Initialize this repository with a README 初始化带有一个 README 的项目
  • Add .gitignore 添加 git 忽略文件
  • Add LICENSE 添加协议

说明这几个选项应该是大部分开源项目都应该具备的,前提当然是你有心开源你的项目

那么,下面就如何整理自己在 Github 上的开源项目,分享一点自己的心得

利用好 .gitignore

我觉得 .gitignore 翻译过来可以理解为 git 忽略文件。当你有不想上传的文件存在在你的项目中时,就可以通过编写 .gitignore 文件使得在上传整个项目的时候自动忽略掉不想上传的文件,IDE 的配置文件,out目录等。

为什么要忽略一些文件呢

如果你不明白为什么,那么可以看一下你平常提交的东西,除了更新的代码之外,还包括大量的 IDE 配置文件的修改,out 目录的更新等等。

怎么查看呢?

你可以随意打开一个用 IDE 开发的项目,Github 会记录你每次的提交

点击那个 commits 后,再随意点击几个你的 commit 记录,你会发现有时候可能你都没有写代码,仅仅只是更新下配置,整个上传的东西都特别多,甚至很多你都看不懂,这些东西对项目并没有什么影响,当然你在本地开发的话,还是需要这些文件的,但是如果是跟别人协同开发,那么每个人在本地打开你的项目的时候都会覆盖原有的项目配置,如果此时合并代码,就会产生很多的冲突。此外,类似于 build 这样的文件夹里的内容都特别大,别人在 clone 你项目时,很大一部分时间都会耗在这种无足轻重的内容上

如何编写 .gitignore 文件

在新建 Github 仓库时,可以通过根据你当前的项目类型,选择对应的 .gitignore 文件,比如我要上传我的 Android 项目,那么我就选择 Android,但是这样是远远不够的。

这里推荐一个网站 gitignore.io,相比于 Github 生成的,在这里你可以选择更多的类型

如果此时我要上传一个 Android 项目,我可以输入 AndroidAndroidStudio 这些关键字

点击 Create 按钮后就会生成一个文件

比较长,这里只显示一点点,你可以自己尝试,也可以点击上面的文件链接进行查看。和 Github 生成的比较一下,就会发现 gitignore.io 生成的会更加全面。

把全部内容复制下来,打开你项目的 .gitignore 文件,如果没有的话就新建一个,注意文件名不能写错了,把复制的内容粘贴进去即可。保存,这样在之后的上传中就不会,上传这些被过滤的文件了。

如果你已经上传过项目了,你会发现即使更改了 .gitignore 文件,你 Github 上原本应该过滤的文件还是存在的,只不过并没有更新。既然不更新,那么也就没必要让他占着这么个地方

删除已经提交的文件

我们想要把远端的不需要的文件删去,但是又不想把本地的删掉,此时就可以使用下面的命令来操作

1
git rm -r --cached <files or directory> <files or directory> ...
  • rm 即 remove,删除
  • -r 即 recursion 递归的首字母,表示递归删除目录

如果把 --cached 去掉,那本地和远端的就都删掉了

如果你想在删之前查看一下可以删除的文件,防止出现误删的情况,将 --cached 替换成 -n

1
git rm -r -n <files or directory> <files or directory> ...

确认过后再将 -n 换成 --cached 删除即可,然后再依次 commit ,push 即可

下面来实际演示一下

查看可以删除的远端文件,确认并删除

比如我要把远端的 .idea 目录以及 *.iml 文件删掉,这些都是 Android Studio 生成的项目文件,我可以这么写

1
git rm -r -n .idea *.iml    

接着你会看到列出了一些可以删除的文件列表

确认可删除文件无误后,将 -n 更改为 --cached 进行远端文件删除

然后 commit

1
$ git commit -m ":fire: clean" 

接着再 push 即可

1
$ git push origin master

这里要说明的一点时,我是直接在 master 分支上进行操作的,这并不是个好习惯。一个良好的习惯是建立一个 clean 分支,在分支上进行这些操作,这里只是简单的演示一下。如果有不懂的可以再和讨论 😃

添加 README

如果你确定为开源贡献一份自己的力量(虽然不一定有人看),一个良好的习惯就是编写 README,使用 Markdown 编写 README 并不会用很长时间,如果你不会 Markdown,可以参考 GitHub 官方教程

在我看来,一个良好的 README 至少要包含一下几个方面

  • 项目名
  • 功能/项目描述,包含但不止于项目进度,如何使用等
  • 协议申明

如果你有能力的话,可以考虑再写一份英文版的,虽然我的英语并不好,但我还是会为维护中的项目加一份含有英文描述的 README,毕竟 GitHub 是个全球的社区。如果英文不好,那么也可以借助翻译软件,当然这只是建议,并不一定都得有。

有一个好的 README ,当别人在看到你的项目时,也会对你的项目有一定的了解,这是一份向别人介绍自己项目的说明,应该要好好利用

添加 LINCENSE

如何选择一个协议,可以看看这个 Choose an open source license

英文的看不懂?右键 -> 翻成中文(简体)

虽然我们的项目并不大,协议几乎没什么作用,不过我觉得加一个协议并不会耗多少事,选择一个合适的协议,百利而无一害,何乐而不为呢?😀

如果你想为已经创建的项目添加 LICENSE,可以在 Github 上进行操作

  1. 先在项目对应面板下,点击 Create new file
  2. 接着在输入文件名 LICENSE,接着会出现选择 LICENSE 模板的按钮
  3. 然后你就可以根据需要选择适合自己的 LIECNSE 了

为你的项目添加 topics

我觉得这是一个很容易让人忽略的细节

我们经常维护一个项目,但是一直无人问津,会不会觉得没有动力?

没有宣传是一方面,还有一个原因就是大家的项目名太多重复的了

举个例子,我每天都会在 leetcode 中写一道题,然后将 solution 代码放在我的 Algorithms 这个项目中这个项目主要是放一些我在 leetcode 的题解以及我的算法实践的代码,因为我主要是用 Kotlin 来写的代码,此外还有部分 Java ,JavaScript,Python 的代码,所以这个项目就变成了一个 Kotlin 为主要语言的项目了。

有一次我突发奇想,在 Github 上以 kotlin leetcode 为关键字去搜索,的确也看到了很多项目,但是项目名都大同小异,不过令我困惑的是我翻了好几页都没有发现我的项目,后来我为项目添加了好几个 topics

现在再以 kotlin leetcode 为关键字去搜索,就可以在第一页发现我的项目。可见,为自己项目添加合适的 topics 是很多人都忽视了的一个细节。

此外,在搜索结果中,除了项目名,star 数外,另一个能简洁描述你项目的就是 Description,为你的项目添加简洁的描述也是一个让别人了解你项目的很好的方式

总结

如果你有认真的做上面说的几件事,可能有时候你就会发现偶尔有陌生人来 star 或者 fork 你的项目,这种被陌人生肯定的感觉也是一种坚持开源的很好的动力 🎉

虽然使用 GitHub 很长一段时间了,但是还有很多东西需要学习,上面分享的也是我觉得大家平时容易忽略的东西,希望能有一定的帮助。

Author: Inno Fang
Link: http://innofang.github.io/2018/03/09/%E5%A6%82%E4%BD%95%E7%AE%A1%E7%90%86%E4%BD%A0Github%E4%B8%8A%E7%9A%84%E5%BC%80%E6%BA%90%E9%A1%B9%E7%9B%AE/
Copyright Notice: All articles in this blog are licensed under CC BY-NC-ND 4.0 unless stating additionally.