git add .로 불필요한 파일이 섞이지 않도록 개별 파일 지정 방식으로 변경하기

작업 후에 git add .를 사용하여 한꺼번에 staging 하면, 의도하지 않은 파일까지 커밋 후보에 포함될 수 있습니다.

제 리포지토리(Repository)에서는 기사 원고, Qiita CLI 관리 파일, 생성물, 로컬 설정이 동일한 작업 트리(Working Tree)에 나열될 수 있습니다. 그 상태에서 git add .를 사용하면, '이번 변경 사항'과 '우연히 존재하던 변경 사항'이 섞이게 됩니다.

이 기사에서는 git add .를 그만두고 개별 파일 지정 방식으로 전환한 운영 방식을 정리합니다.

문제는 git status를 보고 있어도 staging의 입도(Granularity)가 거칠다는 점이었습니다.

예를 들어 기사 1건만 수정했을 뿐인데도, 작업 트리에는 다음과 같은 변경 사항이 동시에 남아 있을 수 있습니다.

M README.md
M drafts/article-ideas.md
?? articles/new-post.md
...

이 상태에서 git add .를 실행하면, 현재 디렉토리 이하의 변경 사항이 통째로 staging 됩니다.

기사 본문만 커밋하고 싶은데, 후보표, Qiita CLI의 remote 캐시, 로컬 설정까지 섞일 가능성이 있습니다.

git add .는 '이번 의도'를 알지 못합니다.

Git의 관점에서 보면, 변경된 파일도 추적되지 않은(Untracked) 파일도 현재 디렉토리 하위에 있는 변경 사항일 뿐입니다. 사람에게는 '방금 만진 기사'와 '전부터 남아 있던 로컬 파일'이 다르더라도, 명령어는 이를 구분하지 않습니다.

특히 위험한 파일은 다음과 같습니다.

• .env, .env.local과 같이 비밀 정보를 포함할 수 있는 파일
• CLI가 생성한 .remote나 캐시
• 로컬 환경에서만 사용하는 설정
• 다른 태스크에서 작업 중이던 파일
• 생성된 lockfile이나 이미지 등, 이번 변경 이유를 설명하기 어려운 파일

.gitignore가 있더라도, 아직 ignore에 넣지 않은 파일이나 이미 추적(Tracking) 중인 파일은 방지할 수 없습니다.

제 운영 방식에서는 git add .와 git add -A를 원칙적으로 사용하지 않고, 커밋에 포함할 파일을 명시하도록 했습니다.

git status --short
git diff -- qiita/public/example.md
git diff -- drafts/qiita-article-candidates.md
...

포인트는 git add 전후로 확인하는 것을 나누는 것입니다.

• git status --short: 변경 전체를 확인
• git diff -- <file>: staging 전에 대상 파일의 내용을 확인
• git add <file>: 포함할 파일만 staging
• git diff --cached: staging 된 차분(Diff)만 확인

git diff --cached를 통해 이번에 설명할 수 없는 차분이 있다면, commit 전에 멈출 수 있습니다.

여러 파일을 staged 상태로 만들고 싶을 때도 대상을 나열합니다.

git add `
qiita/public/example.md `
drafts/qiita-article-candidates.md `
...

PowerShell에서는 행 끝의 백틱(Backtick)으로 줄바꿈을 할 수 있습니다. 다만, 붙여넣기 실수가 걱정된다면 한 줄로 쓰는 것이 더 안전합니다.

git add qiita/public/example.md drafts/qiita-article-candidates.md README.md

디렉토리 단위로 staging 하는 경우도 대상 디렉토리가 좁을 때만 수행합니다.

git add qiita/public/

이 경우에도 먼저 git status --short qiita/public/로 내용을 확인합니다.

자주 발생하는 함정은 .gitignore에 추가했는데도 여전히 staging 되는 케이스입니다.

한번 Git에 의해 추적된 파일은 .gitignore에 작성하더라도 자동으로 추적 해제되지 않습니다. 추적만 해제하고 싶다면, 파일을 남겨둔 채 index에서 제외합니다.

git rm --cached path/to/local-file

여러 명이 사용하는 리포지토리 (Repository)라면, 이 작업 자체도 커밋 (commit)에 포함되므로 왜 추적을 해제하는지 설명할 수 있는 상태에서 실행해야 합니다.

AI에게 커밋 준비를 부탁할 때도, "staging 해줘"라고만 하면 범위가 모호해집니다.

저는 다음과 같이 대상 파일을 명시합니다.

다음 파일들만 staging 해주세요.
- qiita/public/example.md
- drafts/qiita-article-candidates.md
...

AI는 작업 트리 (Working Tree) 전체를 보고 "관련이 있을 것 같다"고 판단할 때가 있습니다. 대상 파일을 명시하면 다른 태스크의 변경 사항을 포함시키기 어려워집니다.

개별 파일 지정 방식을 사용하더라도, 대상 파일 안에 비밀 정보가 들어있다면 방지할 수 없습니다.

따라서 최소한 다음 사항을 커밋 (commit) 전에 확인합니다.

git diff --cached

필요하다면 비밀 정보로 의심되는 문자열도 검색합니다.

git diff --cached | Select-String -Pattern "token|secret|password|api_key|connectionString" -CaseSensitive:$false

이 검색은 완벽하지 않습니다. 마지막에는 반드시 diff를 읽어야 합니다.

git add .

은 빠르지만, 작업 트리 (Working Tree)에 여러 태스크의 변경 사항이나 로컬 파일이 있으면 의도하지 않은 차이점 (diff)을 섞게 됩니다.

저의 운영 방식에서는 다음 순서로 고정했습니다.

git status --short

로 전체를 확인한다 -
git diff -- <file>

로 대상만 확인한다 -
git add <file>

로 개별적으로 staging 한다 -
git diff --cached

로 커밋 (commit)에 포함될 차이점 (diff)만 확인한다

커밋 (commit)은 이력 (History)에 남기 때문에, 조금 느리더라도 "왜 이 파일이 들어있는가"를 설명할 수 있는 staging 중심의 방식으로 바꾸는 것이 다루기 훨씬 쉬워졌습니다.