GitHub Tips 🍯

GitHub을 단순히 git remote 저장소로만 사용하고 있다면 GitHub 자체적으로 제공하는 다양한 기능들을 놓치고 있을 것이다. 팀에 생산성 구루가 한명쯤 있다면 여러 팁들을 공유 받거나 이미 적용되어 있을텐데, 보통 이렇게 집착(?)하는 팀원을 보긴 어려울 것이다. 또한 이런 미립자 팁들은 파편화 되어 있어 일일히 찾아보기도 귀찮다.

사내 공유를 계기로 파편화되어 있던 팁들을 바로 적용해 볼 수 있도록 한 곳으로 모아봤다. 현재 팀에서 GitHub을 사용한다면 하나씩 적용해보자. 몸에 익고, 팀원들이 함께 이해하고 사용하다보면 분명 이전보다 나은 업무 환경이 될 것이라 생각한다.

GitHub 단축키

단축키를 이용하면 특정 목적지까지 여러 스탭의 액션을 거치지 않고 바로 접근할 수 있다. 아래는 개인적으로 자주 사용하는 단축키들이다. 모든 단축키에 대해 궁금하다면 Keyboard shortcuts을 참고하길 바란다.

• g c — Code 화면으로 이동
• g i — Issues 화면으로 이동
• g p — Pull requests 화면으로 이동
• g w — Wiki 화면으로 이동
• t — 파일명 검색(Fuzzy file finder)
• / — 검색
• cmd / — (이슈/PR 목록에서) 내부 검색
• ctrl ., ctrl 1 — 저장된 코맨트 사용하기
• ? — 현재 화면에서 사용할 수 있는 단축키 설명

🤔 GitHub 뿐만 아니라 모든 웹사이트에서 공통된 단축키를 활용하기 위해서 나는 크롬 브라우저의 Vimium 확장프로그램을 사용하고 있다. GitHub 기능은 아니지만 익숙해지면 생산성이 꽤 좋아져서 남긴다.

https://dzone.com/articles/vimium-a-browser-for-hackers

🤔 크롬 검색엔진을 활용하면 좀 더 빠르게 GitHub 이슈/PR에 접근할 수 있다. 크롬 브라우저에서 chrome://settings/searchEngines 에 접근하여 검색 엔진을 추가하면 된다. 현재 우리팀은 plan이란 repo를 중점으로 업무를 진행하는데, 이 repo의 검색 URL을 검색 엔진으로 추가하여 GitHub 접근 > repo 접근 > 검색창 클릭의 단계를 거치지 않고 바로 검색할 수 있어 굉장히 유용하다.

➥ Search engine: Plan
➥ Keyword: pl
➥ URL with %s in place of query: https://<github-url>/<org>/plan/issues?utf8=✓&q=is%3Aissue+is%3Aopen+%s

https://www.sunnymistry.dev/til/tag/chrome/

Markdown/Comment 관련

기본적인 마크다운 문법은 모두가 알테니 설명하지 않으며, 기본적인 것 외에 다양한 마크다운 사용법과 코맨트 남길 때 유용한 기능들에 대해서 설명한다.

Issue/PR 본문에 ‘접기/펼치기’ 추가하기

보고서를 잘 작성해야하는 것과 동일하게 이슈/코맨트/PR 본문들도 잘 작성해둬야 한다. 부가 설명이나 숨겨둘 필요가 있는 소스코드 등을 나타낼 때 접을 수 있는 콘텐츠(collapsible content)를 활용할 수 있으며, 아래와 같이 작성한다.

<details>
<summary>Details</summary>

```kt
println("Hello World")
```

</details>

⚠️ Warning: <summary> 태그 이후에 개행이 있어야 함.

접은 상태(왼쪽) / 펼친 상태(오른쪽)

키보드 태그 사용하기

마크다운에 <kbd> 태그를 사용하면 키보드 버튼과 같은 UI를 나타낼 수 있다.

GitHub Protips: Tips, tricks, hacks, and secrets from Lee Reilly — The GitHub Blog

Hex 색상 코드 나타내기

마크다운에 #C6E48B 같은 hex code로 표현된 색상을 코드 블럭에 작성하면 아래와 같이 색상이 같이 표현된다.

GitHub Protips: Tips, tricks, hacks, and secrets from Lee Reilly — The GitHub Blog

코드 문법 하이라이팅 — diff 문법

코드 블럭을 작성할 때 ``` 다음에 언어 식별자를 작성하면 하이라이팅을 적용할 수 있다. 추가적으로 프로그래밍 언어 식별자 말고, diff도 있으니 필요한 경우가 있으니 사용해보자.

https://stackoverflow.com/a/40883538/3793078

코드 스니펫 추가하기

현재 저장된 코드의 일부를 남겨야할 때 직접 소스 코드를 입력하지 않고 아래와 같이 스니펫을 추가할 수 있다. 사용 방법은 여기를 참고하길 바란다.

Creating a permanent link to a code snippet — GitHub Docs

코맨트에 답변 남기기

특정 코맨트에 답변을 남길 때 ‘Quote reply’ 버튼을 사용하면 해당 코맨트를 내용을 자동으로 추가해준다. 이를 통해 작성하면 어떤 코맨트에 대한 답변인지 파악하기 쉬워진다. ‘Quote reply’ 버튼은 단축키 r로 대체할 수 있다.

추가적으로, 답변을 남길 특정 코맨트의 내용을 드래그한 뒤 ‘Quote reply’를 클릭하면 드래그한 본문의 내용만 인용할 수 있다.

Quote reply to a comment — The GitHub Blog

Anchors 추가하기

특정 코맨트를 참고 링크로 추가할 때 코맨트 생성일을 클릭하여 주소를 복사해서 사용할 수 있다. 그럼 특정 코맨트의 특정 문구/위치를 참고 링크로 남길 땐 어떻게 할까? 방법은 간단하다. 마크다운은 HTML 태그를 지원하니 직접 앵커를 만들어줄 수 있다.

아래와 같이 <a name=""></a>태그를 원하는 위치에 추가하고, 해당 앵커를 # 을 통해 링크를 만들어준다.

### <a name="toc"></a>목차
<a name="reference"></a>
...
참고 자료는 [여기](#reference)를 확인하라.
[목차 바로가기](#toc)

Note, Warning 블락 사용하기

Asciidoc에 있던 기능이 GitHub markdown에도 추가되었다. 이슈, PR, discussions, 릴리즈 노트 등에 적용이 가능하며, 보다 가독성 있는 문서를 작성할 수 있다. (참고 논의)

> **Note**
> This is a note

> **Warning**
> This is a warning

자주 쓰는 답변 저장하기

마크다운 에디터의 오른쪽 상단을 보면 화살표 아이콘이 하나 있는데, 자주 쓰는 답변을 저장해서 바로 바로 사용할 수 있게 해준다(보통 LGTM👍이 가장 많이 사용되지 않을까 생각한다).

Using saved replies — GitHub Docs

🤔 emoji 활용해보자. 직접 이모지를 입력할 수도 있지만, GitHub 자체적으로 특정 키워드를 통해서도 지원한다. (예를 들면, 자동화 도구를 만든다거나 자주 쓰는 답변에 추가할 때 활용할 수 있다)
➥ ref: ikatang/emoji-cheat-sheet

코맨트 숨기기

GitHub을 협업 도구로 사용하고 있다면 이슈에서 대부분 커뮤니케이션이 이뤄질 것이다. 이 때 커뮤니케이션이 오랫동안 이어지면 자연스럽게 코맨트가 많아진다. 이러한 코맨트들은 변경된 내용도 많고, 더 이상 불필요하거나 중복된 코맨트도 많을 것이다. 이것들을 그대로 유지하면(펼쳐두면) 핵심 내용 혹은 코멘트가 잘 안보이게 된다. 이러한 문제점을 해결하기 위해 GitHub에서는 코맨트 숨김 기능을 제공한다.

Hiding a comment — GitHub Docs

작업 당시에는 바로 스크롤을 내린다던가 봐야 할 코맨트를 알고 있으니 상관 없겠지만, 항상 문제는 시간이 지난 뒤에 발생한다. 나중에 해당 작업건 히스토리를 파악하고자 할 때 핵심 코맨트만 보인다면 많은 시간을 아낄 수 있을 것이다.

코맨트 변경 이력 보기

GitHub은 협업 도구이다. (버전 관리 하는) Git이 아니므로 협업을 위한 다양한 기능을 제공하고 우리는 이를 활용해야 한다. GitHub에서 가장 많이 사용되는 기능 중 하나가 코맨트일 것이다. 코맨트는 변경이 가능하고 변경 이력도 관리해주므로 코맨트를 작성하는데 너무 부담 갖지 말고, 리팩토링 하듯이 내용도 개선해나가자.

Viewing a comment’s edit history details — GitHub Docs

대화 이력 잠그기

업무를 하다보면 이슈나 PR 내에서 어느 정도 커뮤니케이션이 이뤄지고 해결된 이슈들이 많아질 것이다. GitHub에서는 이슈의 대화 이력을 잠그는 기능을 제공한다. (물론 그런 일은 없겟지만) 이를 통해 나중에 이슈를 찾아봤을 때 이슈가 조작되거나 코맨트가 삭제되는 것을 방지한다.

Locking conversations — GitHub Docs

Issue/Pull Request 관련

이슈와 PR에 관련해서 공통된 기능들에 대해 설명한다.

이슈 매니징 — Assignee, Participant

업무를 진행할 때 해당 이슈에 담당자만 assignee로 지정하자. 관습처럼 모든 팀원을 지정한다면 해당 기능은 하느니만 못한 설정이 될 것 이다. (담당시 알람 기능 혹은 개인 업무 필터링 불가)

Assigning an individual issue or pull request — GitHub Docs

담당자가 아니지만 해당 이슈를 추적하고 싶다면 Subscribe 를 통해 Notification을 받을 수 있다. 반대로 해당 이슈에 대한 이벤트를 안받고 싶다면 Unsubscribe 해두면 된다.

또한, 해당 이슈에 코맨트를 남기면 자동으로 Participants에 추가되므로 관련자 파악이 용이하다.

PR/이슈 연결하기

GitHub에서는 (실제 작업을 나타내는) PR과 (작업의 시작을 나타내는) 이슈를 연결해준다. 이렇게 연결해줌으로써 시간이 지난 후에도 히스토리 파악이 쉬워지고 직관적인 UI/UX을 제공하므로 이슈와 PR에 중복으로 작업 내용을 구구절절 설명할 필요가 없어진다.

이슈를 연결하는 방법에는 2가지가 존재한다. 첫번째는 URL 또는 레퍼런스를 통해 이슈 타임라인에 연결됨을 표시하는 방법이다. 단순히 이슈/PR 본문에 이슈/PR 링크를 추가하면 된다. 또한 GitHub의 내부 URL(Raw reference)일 경우 자동으로 Short link로 변환해준다. URL 이외에 별도 prefix(#)를 통해서도 연결이 가능하다.

Autolinked references and URLs — GitHub Docs

두번째 방법으로는 사이드바에 있는 ‘Linked issues’ 를 통해 직접 연결하는 방법이다. 이 방법으로 연결시 타임라인 외에도 사이드바, 이슈/PR 목록에 연결됨을 나타내므로 이전 방식보다 직관적인 UI/UX를 제공한다.

Linking a pull request to an issue — GitHub Docs

이슈 리스트내에 연결된 PR 링크 표시

🤔 커밋 메세지에도 관련 이슈/PR 번호 혹은 commit hash를 남겨두자. 이와 같은 데이터들은 대부분의 툴에서 자동으로 링크를 만들어주므로 유지보수 측면에서 도움을 준다. 커밋할 때 약간의 시간을 할애해보자. 이것이 나중에 히스토리 뒤지는데 많은 시간 낭비를 줄여줄 것이다. (본인뿐만 아니라 팀원 모두)

https://www.jetbrains.com/help/idea/investigate-changes.html

🤔 ZenHub을 사용중이라면 PR에 생성되는 ‘Connect with an issue’를 통해서도 연결해주자. 업무 관리하는데 분명 도움이 될 것 이다.

https://blog.zenhub.com/github-issue-pull-request-linking/

PR을 통해 이슈 닫기

PR에 특정 키워드와 함께 Raw reference를 적으면, PR과 이슈가 연결됨과 동시에 PR이 닫힐 경우(= 작업이 완료된 경우) 해당 이슈가 자동으로 Close 된다. 단순히 Raw reference만 적어서 이슈를 연결할 경우 타임라인에만 추가되는데, 키워드를 사용하면 ‘Linked issues’에 자동으로 등록되므로 활용도가 높다.

Linking a pull request to an issue using a keyword — GitHub Docs

이슈/PR 템플릿 만들기

PR 생성시 템플릿을 제공할 수 있다. .github/PULL_REQUEST_TEMPLATE.md 파일을 생성하여 제공할 수 있으며, <!-- -->으로 주석도 남길 수 있으니 PR 본문 작성 가이드를 남길 수 있다. 이러한 템플릿 기능은 PR 뿐만 아니라 이슈 템플릿도 생성할 수 있다. 아래에 예시 템플릿 코드도 추가해두었으니 활용해보자.

Issue and Pull Request templates — The GitHub Blog

<!-- Linked issues -->
org/repo#
## Summary
## Test Plan
<!-- 테스트 방법 설명 혹은 TC를 추가했는지-->
## Related services
<!-- 타 서비스와 의존성이 있을 경우 설명 -->
N/A
## References
<!-- 관련 자료가 있을 경우 첨부 및 링크 추가 -->

GitHub에서 온 메일에 답장을 통해 코맨트 남기기

GitHub으로부터 받은 메일에 답변을 통해 코맨트를 남길 수 있다. 이를 활용한다면, CI 서버에서 특정 키워드를 통해 트리거되도록 설정되어 있을 때 메일 답변을 통해 바로 해당 작업을 실행시킬 수 있다.

Reply to Comments from Email — The GitHub Blog

라벨 붙히기

TODO

• 라벨을 통한 릴리즈 노트 분리

Managing labels — GitHub Docs

Pull Request 관련

PR과 코드 리뷰에 관련된 기능에 대해 설명한다.

diff 볼 때 whitespace 제외하기

PR 내 diff를 볼 때 포맷터가 적용되었거나 공백 변경이 많을 경우 코드 리뷰해야 할 핵심 코드가 잘 보이지 않는다. 이 때 다음 두 가지 방법으로 whitespace 변경을 제외할 수 있다.

• ‘Diff settings’에서 ‘Hide shitespace changes’ 선택하기
• diff URL에서 ?w=1 추가하기

Ignore Whitespace — tiimgreen/github-cheat-sheet

Merge 된 브랜치 자동 삭제하기

PR을 통해 작업이 완료되었을 때 브랜치 삭제를 깜빡하는 경우가 있다. 이를 해결하기 위해 GitHub은 머지된 브랜치를 자동 제거해준다. repo의 ‘Settings’에서 ‘Merge button’ 섹션 아래에서 해당 설정을 활성화할 수 있다.

Managing the automatic deletion of branches — GitHub Docs

제거된 브랜치 복구하기(Restore)

GitHub엔 PR에서 제거된 브랜치를 복구하는 기능이 있다. 아마 자동 제거하는 기능이 있으니 복구하는 기능도 있는 것으로 보인다. 그러니 머지된 브랜치 자동 제거에 예민할 필요가 없다.

Restoring a deleted branch — GitHub Docs

🤔 머지된 브랜치를 별다른 이유 없이 유지할 필요는 없다. Git 개념에서 Remote의 역할을 생각해보자. Remote는 협업 구조에서 작업을 공유하는 공간이다. 즉, 작업이 완료된 이후에 버전 관리를 위해서 브랜치를 남겨두는 곳이 아니다. 버전 관리를 위해서는 git의 tag나 GitHub의 release를 활용해야 한다.
또한, 작업 이력에 커밋을 남기는 방식에 대해서는 머지 방식을 컨트롤 할 줄 알아야 한다. 브랜치의 커밋을 유지하려면 fast-forward merge 혹은 3-way merge를 해야 하고, 상황에 따라 squash merge를 사용할 수도 있다. (단순히 브랜치를 남기자는 것 보다 브랜치에서 필요에 맞게 커밋을 하고 메인 브랜치에는 어떻게 커밋할지 생각할 줄 알아야 한다는 말)
경험에 따르면 브랜치를 남겨두는 것은 GitHub 이외의 3rd-party 시스템에서 브랜치 검색시 불필요한 브랜치(실제 작업중인 브랜치)를 보여주는 경우가 발생한다. 이러한 시스템에서 불필요한 브랜치 정보들은 노이즈가 된다.
➥ ref: Git Merge — Atlassian Git Tutorial
➥ ref: What’s the difference between tag and release? — stackoverflow

머지된 브랜치 롤백하기(Revert)

머지된 PR에 버그가 있어서 패치보단 롤백이 필요할 경우가 있다. 이 때 GitHub의 PR Revert 기능을 활용하면 쉽게 롤백 할 수 있다. 이것은 Git의 기능은 아니며 GitHub에서 해당 작업 건을 역으로 commit하는 기능이다. 이 기능은 가끔 다른 브랜치와 충돌시 꽤나 복잡한 상황을 만드므로 commit의 히스토리 상태를 인지하고 사용하길 바란다.

Reverting a pull request — GitHub Docs

PR 머지 방식 제한하기

GitHub은 PR의 Merge 방법을 강제하거나 일부 허용할 수 있는 설정을 제공한다. Git을 처음 접한 사람이면 아마 3-way merge 혹은 fast-forward merge를 주로 사용할 것이다. 이러다 시간이 갈수록 기판 같아 보이는 브랜치/커밋 로그를 보면 다른 브랜치 머지 방법을 사용할 것이다. 하지만 Git 숙련도가 부족할 때 rebase를 마구 사용하다보면 브랜치가 꼬여 진짜 헬을 맞이할 수도 있다.

Configuring pull request merges — GitHub Docs

Draft PR 생성하기

어떤 PR이 작업중인지, 버려졌는지 단번에 확인할 수 있을까? 생성된지 오랜 시간이 지난 후에 브랜치 생성자에게 물어보는 방법도 있고, WIP 라벨링을 활용할 수도 있지만, 아예 Draft PR로 생성하여 작업중인 (혹은 임시) PR이라는 것을 단번에 나타낼 수 있다. 이렇게 GitHub 기능을 활용하면 직관적인 UI로 표현할 수 있으니 커뮤니케이션 비용을 줄일 수 있다.

Introducing draft pull requests — The GitHub Blog

일반 PR로 생성했다가 다시 Draft로 되돌릴 수도 있으니 변경에 대해서 걱정할 필요 없다. (GitHub Enterprise 2.21.0 부터 적용)

Converting a pull request to a draft — GitHub Docs

코드 리뷰에서 코드 제안하기

이전에 diff 코드 블럭 하이라이팅을 설명하였다. 코드 리뷰엔 diff UI와 비슷하지만 실제 코드에 대해서 제안할 수 있는 suggestion 기능이 있다. 단순 하이라이팅 기능인 diff 와 다르게 코드 리뷰에 중점을 두었고, 바로 코드로 적용할 수도 있게 한다.

Applying suggested changes — GitHub Docs

여러 줄에 코드 리뷰 남기기

코드 리뷰시 리뷰를 남길 코드 라인을 드래그 혹은 라인 넘버 선택 후 Shift 누른채 다른 라인 넘버를 선택하면 여러 코드 라인에 리뷰를 남길 수 있다.
(GitHub Enterprise 2.21 부터 적용)

Multi-line code suggestions general availability — The GitHub Blog

코드 리뷰시 파일마다 리뷰 체크해두기

코드 리뷰시 확인한 파일에 대해 체크해둘 수 있다(Viewed). 이를 통해 PR을 틈틈히 리뷰할 수도 있고, 해당 PR에 변경이 있을 경우 변경된 파일에 대해서만 체크 해제 상태로 바뀌니 보다 빠르고 편하게 리뷰할 수도 있다. 참고로 체크박스 상태는 페이지를 떠나도 유지된다.

Mark files as viewed — The GitHub Blog

리뷰 해결 처리하기

리뷰 받은 내용에 대해서 코드를 수정하더라도 PR 내 Conversation 탭에서는 그대로 보여진다. 이미 리뷰 확인 및 반영이 되었음에도 불구하고 리뷰 내용을 남겨두면 해당 PR을 볼 때 계속 펼쳐진 상태로 보여지게 된다. 나중에 반영되었는지 다른 의견이 있어서 유지했는지 코맨트를 하나하나 읽어봐야하는 경우가 발생한다.

해결 처리한 리뷰는 ‘Resolve conversation’ 버튼을 통해 닫아주자. 해결 처리된 이슈는 UI적으로 닫혀지는데 확인이 필요하면 언제든 열어서 볼 수 있다.

Resolving conversations — GitHub Docs

숨겨진(Outdated) 대화들 한번에 열어보기

코드 리뷰 받고 좀 늦게 참가하면 오래된 대화들은 모두 숨김 처리가 된다. 숨김 처리된 대화의 Show outdated 버튼을 통해 해당 내용을 펼쳐볼 수 있는데, 이 때 alt 와 함께 클릭하면 숨겨진 모든 대화들을 일괄로 열 수 있다.

Changes in pull requests — GitHub Docs

CODEOWNER 지정하기

각 디렉토리 혹은 확장자 별로 코드 오너를 지정할 수 있다. 주어진 포맷으로 .github/CODEOWNERS파일을 작성하기만 하면 된다. 코드 오너를 지정해두면 PR 생성시 리뷰어로 자동 등록될 뿐만 아니라 브랜치 보호 규칙 설정시 코드 오너의 리뷰 여부도 설정할 수 있다.

About code owners — GitHub Docs

Introducing code owners — The GitHub Blog

(추가적으로) 리뷰어를 지정하는 Auto Assign 앱을활용할 수 있다.

코드 리뷰, Auto Assignment 설정하기

https://docs.github.com/en/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team#configuring-auto-assignment

Wiki 관련

GitHub에서 제공하는 Wiki 관련된 기능에 대해 설명한다. 이를 통해 Confluence Wiki 못지 않은 문서를 만들 수 있다.

로컬에서 페이지 작성/편집하기

GitHub의 Wiki는 웹 뿐만아니라 로컬에서도 생성/수정이 가능하다. Wiki는 별도의 리모트 URL이 있으며 git으로 관리된다. 즉, 형상 관리도 가능하고 이미지나 디렉토리, 문서 이외의 파일도 업로드할 수 있다.

Adding or editing wiki pages locally — GitHub Docs

Sidebar/Footer 사용하기

Wiki에 문서를 생성하다보면 오른편에 ‘Pages’에 알파벳순으로 하나씩 쌓이게 된다. 하지만 문서의 구조를 정리하고 원하는 목차를 표현하고 싶을 수 있다. 이 때 Sidebar를 사용하면 된다. 추가적으로 Sidebar 이외에 Footer도 있으므로 활용하길 바란다.

로컬에서 Sidebar/Footer를 추가하려면 _Footer.<extension> 혹은 _Sidebar.<extension> 이름으로 파일을 생성하면 된다.

Sidebar, Footer 예 (Creating a footer or sidebar for your wiki — GitHub Docs)

Wiki에서 페이지 링크를 작성할 때 기존 마크다운과는 다른 문법을 지원한다. 기존 마크다운 문법보다 간결하게 해주며 크게 두 가지 방법이 있다.

첫번째는 [[File Name]]이다. 여기서 주의할 점은 실제 파일명이 Metrix-Definitions.md 지만 표기할 땐 대시(-)를 공백으로 표기한다. 예를 들면, [[Metrix Definitions]] 로 작성한다.

두번째는 [[<Display Name>|<File Name>]]로 표기하며, 파일명과 다르게 보여주고 싶을 때 사용한다. 예를 들어, Developer-Edition-살펴보기.md을 ‘Developer Edition’으로 표기하고 연결하고자 할 경우 [[Developer Edition|Developer Edition 살펴보기]]로 작성한다.

참고로 File Name을 작성할 때 주의할 점이 있다. 마크다운과 연결하려는 페이지가 같은 디렉토리에 있어야 한다.

마크다운(왼쪽) / 렌더링된 화면(오른쪽). (Adding links — GitHub Docs)

디렉토리 구조 분리하기

GitHub Wiki는 git으로 관리할 수 있으므로 디렉토리를 구분해서 파일을 관리할 수도 있다. 예를 들면 어드민과 관련된 페이지를 모아두기 위해 ./admin 디렉토리를 생성하면 되므로 간단하다.

./
├── Home.md
├── _Footer.md
├── _Sidebar.md
└── admin
    ├── Monitoring.md
    └── _Sidebar.md

디렉토리를 나누면 각 디렉토리별로 _Sidebar.<extension>, _Footer.<extension>을 가질 수 있으므로 좀 더 문서다운 UI를 제공할 수 있다.

왼쪽은 루트 디렉토리에 있는, 오른쪽은 admin 디렉토리내에 있는 Sidebar이다.

이미지 추가하기

Wiki에서는 PNG, JPEG, GIF 이미지를 지원한다. 에디터에서 바로 추가할 수 있다.

Adding images — GitHub Docs

로컬에서 작업할 경우 이미지들을 디렉토리로 분리하여 관리할 수도 있다. 예를 들면, 이미지들을 ./images디렉토리에 모아두고, 마크다운에서[[images/sonarlint.png]]로 작성하면 이미지를 보여줄 수 있다. 참고로 상대주소로 인식되므로 주의하기 바란다.

./
├── Home.md
├── _Footer.md
├── _Sidebar.md
├── admin
│   ├── Monitoring.md
│   ├── _Sidebar.md
│   └── images
└── images
    └── sonarlint.png

변경 이력 보기

Wiki는 Git으로 관리되므로 당연히 형상관리가 가능하다. 그러므로 git log를 볼 수 있다. GitHub은 웹에서 Wiki 페이지의 변경 이력 또는 리비전 비교 및 롤백 기능을 제공한다.

Viewing wiki history — GitHub Docs

Viewing previous content — GitHub Docs

Comparing two revisions — GitHub Docs

검색하기

GitHub에서는 다양한 검색 기능을 제공한다. 대부분 키워드를 통한 방법이며 Wiki 내용을 필터링해서 검색할 수도 있다. 다양한 옵션은 공식 문서를 확인하길 바란다.

ref: Searching wikis — GitHub Docs

기타

Branch Protection Rule

Remote에 있는 브랜치에 보호 규칙을 정할 수 있다. 와일드 카드 문법(*)을 사용하면 여러 브랜치에 규칙을 지정할 수 있다. 팀에서 별도의 브랜치 전략을 사용하고 있다면 유용할 것이다.

Managing a branch protection rule — GitHub Docs

보호 규칙 중 일부를 아래 적어두었다. 아마 가장 많이 사용하는 규칙은 ‘필수 리뷰어 수 지정’과 ‘status check 확인’ 일 것 같다. 이 외에도 많은 옵션이 있고 계속 추가되므로 공식 문서를 확인해보길 바란다.

• PR 머지 전 리뷰 확인
• 필수 리뷰어 수 지정
• 신규 커밋 push될 경우 approve 상태 해제
• Code Owner의 리뷰 확인
• PR을 닫을 수 있는 사람 제한
• PR 머지 전 status check 확인
• PR 머지 전 대화 resolved 상태 확인
• 해당 브랜치로 push 사용자 제한
• force push 제한
• 브랜치 삭제 제한

Custom Tabs 사용하기

GitHub Enterprise(GHE)에는 ‘Custom tabs’ 기능이 있다. repo 내비게이션바에 특정 URL과 연결된 버튼을 추가하는 기능이다. repo 설정이므로 팀원 모두에게 적용된다. 참고로 한번 추가한 뒤 순서 변경이 안되므로 순서 변경이 필요할 경우 원하는 순서에 맞게 제거 및 추가 작업이 필요하다.

GHE 2.21에 @me 검색 쿼리가 추가되었는데, 커스텀 탭과 태그를 활용하면 리뷰해야할 PR 모아보는 링크를 추가할 수 있다.

Searching on GitHub — GitHub Docs

• review-requested:@me: 나를 리뷰어로 등록한 PR이 노출된다. But, 리뷰한 PR의 경우 제외된다.
• -reviewed-by:@me: ‘Review changes’를 통해 ‘Comment’, ‘Request changes’, ‘Approve’를 했을 경우 해당 PR을 제외한다. 단순 코맨트의 경우 실제 리뷰 처리가 아니므로 노출된다.
• -author:@me: 내가 생성한 PR에 대해서 제외한다.

GHE 2.22 이후부터 커스텀 탭은 내비게이션바에 바로 노출된다.(왼쪽은 v2.22 이전)

Custom Autolink reference 사용하기

기존에 이슈 트래킹으로 JIRA를 사용하고 있었다면 PR에 관련 이슈를 남기기 위해 JIRA 이슈 링크를 추가했을 것이다. 매번 전체 링크를 추가하는 번거로움을 피하기 위해 GitHub에는 Autolink references 사용해보자. 특정 prefix로 시작되는 문자일 경우 링크로 변환해주는 기능이다. (GHE 2.19 에 추가됨)

🤔 사내에 별도 문서 시스템이 있다면 해당 시스템의 prefix를 활용할 수도 있다.

Configuring autolinks to reference external resources — GitHub Docs

🤔 Intellij IDEA에도 특정 prefix를 링크로 만들어주는 Issue Navigation 기능이 있다.

디폴트 브랜치 변경

GitHub내에 디폴트 브랜치는 변경할 수 있다. 처음 repo를 생성하면 master 브랜치가 기본으로 생성되고 이 브랜치가 디폴트 브랜치로 설정된다. 팀에서 사용하는 디폴트 브랜치로 바꿔보자. 예를 들면 develop이나 main 브랜치일 수 있다.

Changing the default branch — GitHub Docs

브랜치명 변경

기존에 브랜치를 변경하려면 git 명령어를 통해 로컬에서 push 하거나 GitHub에서 새로운 브랜치를 생성하고 이전 브랜치를 지우는 등 우회 방안을 찾았을 것이다. 2021년 1월쯤 기존 브랜치의 이름을 바꾸는 기능이 추가되었으니 이것을 활용하여 리네이밍하자. (GHE 3.1에 추가됨)

Renaming a branch — GitHub Docs | Support for renaming an exising branch — The GitHub Blog

🤔 Main 브랜치? 2020년 10월경 GitHub 업데이트 이후 신규 repository 생성시 master가 아닌 main으로 default branch가 생성된다. IT 업계에서는 master/slave, blacklist/whitelist 와 같은 용어에 대해서 논란이 있어왔다. 이런 이슈를 해결하기 위해 GitHub은 디폴트 브랜치명을 main으로 바꾸었다.
이러한 변경은 GitHub 뿐만 아니라 IT 전반적으로 진행되었다. Git은 2.28.0 버전에 init.defaultBranch라는 옵션을 제공하였고, Jenkins는 “slave”라는 용어를 “agent”로 바꾸었다. (신입이 main 브랜치를 가져와 바꾸자고 할 수 있으니 배경 지식을 알아두자.)

➥ ref: github/renaming
➥ ref: The default branch for newly-created repositories is now main — The GitHub Blog
➥ ref: Introducing init.defaultBranch- The GitHub Blog
➥ ref: On Jenkins Terminology Updates — Jenkins Blog

번외) 유용한 응용프로그램

GitHub과 관련된 글이니 작성한김에 GitHub 관련하여 유용한 프로그램도 소개한다. 개인적으로 튜닝의 끝은 순정이라고 Git과 GitHub 기본 기능만 쓰려하지만 Trailer나 Refind GitHub은 사용하다 없으면 생산성이 꽤나 떨어져서.. 내게 필수 응용 프로그램이 되었다.

Applications

• GitHub CLI
• Trailer — Managing Pull Requests and Issues For GitHub & GitHub Enterprise 👍

Chrome Extensions

• Refined GitHub 👍👍
• Better Pull Request for GitHub 👍
• Notifier for GitHub
• GitHub Issue Link Status

Web

• https://github.githistory.xyz/
  특정 파일에 히스토리를 시각화해서 보여주는 기능
• https://initialcommit.com/tools/git-story
  커밋 히스토리를 애니메이션으로 만들어주는 기능

마치며

내가 사용하는, 알고있는, 추천하는 모든 팁들을 적어봤다. 분명 GitHub 본인들도 사용하면서 어떻게든 생산성을 높히기 위해 만든 기능들일테니 한번 사용해보자.

소개한 팁들 외에도 정적인 페이지를 제공할 수 있는 GitHub Pages, 업무 자동화를 위한 GitHub Actions, 다양한 확장 프로그램을 만들기 위한 GitHub APIs 등 GitHub을 활용하는 방법 및 팁은 너무나도 많다. GitHub의 다양한 기능들이 대해서 궁금하다면 아래 링크를 참고하길 바란다.

GitHub features: the right tools for the job

• GitHub Protips: Tips, tricks, hacks, and secrets from Lee Reilly — The GitHub Blog

이후 업데이트된 기능

• Include diagrams in your Markdown files with Mermaid
• Getting started with project planning on GitHub
• New shortcut: Press . on any GitHub repo.