좋은 커밋을 작성하는 법

computerphilosopher·2021년 6월 13일

왜 커밋을 잘 작성해야 할까?

git을 처음 접하는 사람들은 소스를 백업하는 툴로만 이해하는 경우가 많다.
물론 버전 별 백업 용도로만 사용을 하더라도 최종.zip, 진짜-최종.zip, 리얼-진짜-최종.zip 같은 압축 파일을 주고 받는 형태의 개발보다는 훨씬 낫다. 그러나 잘 작성된 커밋 메시지는 프로젝트의 생산성을 상당히 향상시킬 수 있다. 이번 글에서는 커밋을 잘 작성해야 하는 이유와, 좋은 커밋을 작성하는 방법을 알아본다. '가능하면 50자 이내로 하라', '첫 글자는 대문자로 하라'와 같은 자세한 컨벤션은 다루고 있는 자료들이 많으므로 생략한다.

팀원들이 변경 내용을 쉽게 알 수 있다

내가 작성한 코드는 다른 팀원들에게는 초면이다. 누군가가 코드를 변경할 때마다 모든 팀원이 이를 숙지하는 것은 무리다. 그러나 커밋 메시지를 잘 작성해놓는다면, 자신이 보지 못한 사이에 소스 코드에 어떤 변화가 생겼는지를 쉽게 알 수 있다.

코드의 의도를 알 수 있다

커밋 메시지가 잘 작성되어 있다면 코드를 읽을 때 상당한 도움을 받을 수 있다. git에는 blame이라는 기능이 있다. 다음과 같이 코드의 라인 별로 커밋 메시지를 보여주는 기능이다.

코드를 읽다 보면 원 작성자의 의도를 알 수 없는 부분이 있기 마련이다. Git blame으로 언제, 왜 작성된 커밋인지를 알 수 있다면 코드 읽기가 훨씬 수월해진다. 뭐하는 코드인지도 모르겠는데 커밋에도 fix bug, updated 같은 애매한 메시지만 적혀 있다면 정말 우울해질 것이다. 나아가 aaaa 같은 글귀만 달랑 적혀 있다면 분노가 치밀 것이다.

내가 퇴사하거나 이직하더라도 작성한 코드는 훨씬 더 오랫동안 살아 있다. 코드 자체가 가독성이 좋아서 보조 자료가 필요 없다면 제일 좋겠지만, 그렇지 못하다면 커밋 메시지라도 성의있게 작성하는 것이 다음 사람을 위한 배려이다.

리뷰가 쉽다

팀 작업을 하다보면 머지를 하기 전에 팀원이 코드 리뷰를 해주는 경우가 많다. 특히 신입 사원이라면 더욱 이런 경우가 많을 것이다. 커밋을 잘 작성하면 개발자의 의도를 이해하기 쉽기 때문에 코드 리뷰가 수월하다.

좋은 커밋을 작성하는 법

커밋 메시지를 간결하면서도 분명하게 적는다

커밋 메시지는 '간결함'과 '분명함'이라는 2가지 상반된 과제를 동시에 달성해야 한다. 부득이하게 둘 중 하나를 택해야 한다면 분명함을 택해야 한다. 이 커밋이 무엇을 바꾸는지, 왜 필요한지 등의 내용을 적으면 된다.

들어가야 할 텍스트가 너무 많다면 제목과 본문을 나누어 적을 수 있다. 커밋 메시지에 빈 줄을 하나 추가하면 빈 줄 위의 내용은 제목, 밑의 내용은 본문이 된다. 다음은 쿠버네티스의 한 커밋이다. 제목을 보충하는 내용을 본문에 적은 것을 알 수 있다.

다음으로 커밋 메시지의 반면 교사로 삼을 수 있는 완벽하게 나쁜 사례를 하나 보여주겠다. 내가 대학생 때 기말 과제로 작성한 코드의 커밋 메시지이다.

커밋의 의도는 커녕, 무엇을 변경했는지에 대한 설명도 없다. 게다가 나는 이 프로젝트를 취업용 포트폴리오 중의 하나로 사용하기까지 했다. 커밋 메시지를 제대로 작성하지 않으면 이렇게 큰 망신을 당할 수 있다.

같은 커밋의 변경 사항은 논리적으로 관련성이 있게 한다

앞서 커밋 메시지는 변경 사항을 최대한 간결하면서도 분명하게 기술해야 한다고 했다. 그러나 변경되거나 추가된 코드가 10000줄이 넘는 수준이라면 하나의 분명한 커밋 메시지를 작성할 수 있을까? 유닛 테스트도 수정하고, 기능도 추가하고, 버그도 수정하는 등 여러 작업을 한 번에 커밋한다면 커밋 메시지는 두루뭉술해질 수 밖에 없다.

같은 커밋에 포함되는 코드 변경은 논리적으로 관련성이 있어야 한다. 하나의 제목으로 지칭하기 어려울 정도로 코드의 수정 사항이 많다면 커밋을 여러 개로 쪼개어 하는 것이 좋다.

꼭 필요한 변경 사항만 커밋한다

의도하지 않은 변경 사항이 커밋되는 것은 절대 방지하는 것이 좋다. 예를 들어 코드의 테스트를 하느라 잠깐 설정 파일의 내용을 변경했다면, 설정 파일의 변경 사항은 커밋이 되면 안 된다. git add --all, git add .과 같은 명령어를 애용하는 사람들이 이런 실수를 많이 한다. 저런 명령어는 가급적 없다고 생각하는게 좋다. 귀찮더라도 꼭 필요한 파일만 지정해서 커밋해야 한다.

같은 파일의 변경 사항이더라도, 의도되지 않은 것이라면 커밋하면 안 된다. 코딩 중 실수로 빈 줄이나 공백을 추가하는 경우는 흔하다. 나도 에디터가 멋대로 바꾼 indentation을 모두 포함해 Pull Request한 적이 있다. 논리적으로 보면 별 거 없는 수정사항이었지만, git에는 수백 개의 변경사항이 생긴 것으로 기록되었다.

원하지 않는 변경 사항까지 커밋에 포함하는 습관은, 가독성을 낮출 뿐만이 아니라 충돌 가능성도 높인다. 충돌은 같은 파일의 같은 부분을 동시에 수정하였을 때 생긴다. 커밋의 범위를 충분히 작게 한다면 충돌이 발생할 일이 거의 없다.

이런 사고를 방지하고 싶다면 git add -p 명령을 이용할 수 있다. 코드에 있는 변경사항 중 어느것을 stage할지 일일이 고를 수 있는 기능이다. 가능하면 항상 git add -p를 사용하는 것이 좋다.

이슈 트래커의 티켓 번호를 기록한다

커밋 메시지에 이슈 번호를 기록하면, github에서 자동으로 링크를 만들어준다. #뒤에 이슈 번호를 붙이면 된다. 별도의 이슈 트래커를 사용한다면 본문에 링크해주는 것이 좋다.

해당 이슈에는 내가 한 커밋이 이슈를 언급하였다는 기록이 생긴다. 나중에 이슈를 close하더라도 어떤 커밋을 통해 이슈가 해결되었는지를 쉽게 알 수 있다.

커밋 메시지를 아무리 자세히 작성한다 하더라도, 이슈의 설명을 보는 것보다는 못하다. 코드의 변경 사항을 쉽게 설명할 수 있는 강력한 방법이다.

테스트를 거친 코드만 커밋한다

당연한 말이지만 작동하지 않는 코드를 커밋하면 안 된다. 실은 나도 컴파일이 안되는 코드를 커밋한 적이 있다. 이런 실수를 방지하는 제일 좋은 방법은 자동화된 검증 과정을 넣는 것이다. git hook 기능을 이용하면 커밋이나 push 이전에 원하는 작업을 실행할 수 있다. 여기에 컴파일이나 유닛 테스트 실행 같이 꼭 통과해야 하는 작업을 지정해놓으면 기초적인 실수는 하지 않게 된다.