현재 작업 중인 소스를 기존 GitHub 저장소에 업로드하는 방법 #1

로컬 컴퓨터에서 개발하던 프로젝트를 GitHub에 올릴 때는 단순히 파일을 복사하는 것이 아니라 다음 과정을 거칩니다.

현재 프로젝트 폴더 확인
→ 불필요한 파일 제외
→ Git 저장소 초기화
→ 변경 내용 Commit
→ GitHub 저장소 연결
→ GitHub에 Push

다만 GitHub 저장소가 완전히 비어 있는지, README 파일이 이미 들어 있는지에 따라 방법이 달라집니다.

초보자가 가장 먼저 확인해야 할 내용은 다음 두 가지입니다.

GitHub 저장소가 비어 있는가
GitHub 저장소에 README, LICENSE 또는 .gitignore가 이미 있는가

GitHub 공식 문서에서도 기존 로컬 프로젝트를 처음 Push할 때 오류를 줄이려면 GitHub 저장소를 README, 라이선스, .gitignore 없이 생성하는 방법을 권장합니다. 이미 해당 파일이 들어 있다면 원격 저장소에 별도의 Commit 기록이 존재하는 상태이므로 다른 방법을 사용해야 합니다.

1. 작업 공간

현재 작업 중인 프로젝트 폴더를 다음과 같이 가정하겠습니다.

~/gazebo_ws

GitHub에 미리 만들어 놓은 저장소 주소는 다음과 같이 가정합니다.

https://github.com/hsmaster/gazebo_ws.git

실제 작업에서는 다음 내용을 자신의 환경에 맞게 바꿔야 합니다.

hsmaster
자신 또는 팀장의 GitHub 사용자 이름

gazebo_ws
실제 GitHub 저장소 이름

~/gazebo_ws
현재 프로젝트가 저장된 실제 경로

2. GitHub 저장소 상태부터 확인합니다

GitHub에서 해당 저장소를 엽니다.

저장소 화면에 다음과 같은 안내가 나타난다면 비어 있는 저장소입니다.

Quick setup

파일 목록에 다음 파일이 보인다면 비어 있지 않은 저장소입니다.

README.md
LICENSE
.gitignore
src/
기타 프로젝트 파일

상황에 따라 다음 방법을 사용합니다.

GitHub 저장소가 완전히 비어 있으면 현재 폴더에서 Git을 초기화하고 바로 Push합니다.
GitHub 저장소에 README 등이 이미 있으면 저장소를 먼저 Clone한 후 현재 소스를 복사합니다.
여러 명이 사용하는 팀 저장소이면 별도 브랜치에 업로드하고 Pull Request를 생성합니다.

3. Git이 설치되어 있는지 확인합니다

Ubuntu 터미널을 열고 다음 명령을 실행합니다.

git --version

정상적으로 설치되어 있다면 다음과 비슷한 결과가 나타납니다.

git version 2.34.1

Git이 설치되어 있지 않다면 다음 명령으로 설치합니다.

sudo apt update
sudo apt install git

설치 후 다시 확인합니다.

git --version

4. Git 사용자 이름과 이메일을 설정합니다

Git은 Commit을 작성한 사람을 기록하기 위해 사용자 이름과 이메일이 필요합니다.

다음 명령은 컴퓨터에서 처음 한 번만 실행하면 됩니다.

git config --global user.name "hsmaster"
git config --global user.email "sjyong@humanoidsystem.com"

현재 설정을 확인합니다.

git config --global --list

다음과 비슷하게 표시되어야 합니다.

user.name=hsmaster
user.email=sjyong@humanoidsystem.com

가능하면 GitHub 계정에 등록된 이메일을 사용합니다.

5. 현재 프로젝트 폴더로 이동합니다

터미널에서 현재 작업 중인 프로젝트 폴더로 이동합니다.

cd ~/gazebo_ws

현재 위치를 확인합니다.

pwd

다음과 비슷한 결과가 나와야 합니다.

/home/사용자이름/gazebo_ws

현재 폴더의 파일을 확인합니다.

ls

숨김 파일까지 확인하려면 다음 명령을 사용합니다.

ls -la

ROS 2 프로젝트라면 일반적으로 다음과 같은 파일이나 디렉터리가 있습니다.

src/
build/
install/
log/
README.md

6. 현재 폴더가 이미 Git 저장소인지 확인합니다

다음 명령을 실행합니다.

git status

Git 저장소가 아니라면 다음 오류가 나타납니다.

fatal: not a git repository

이미 Git 저장소라면 현재 브랜치와 파일 상태가 표시됩니다.

조금 더 명확하게 확인하려면 다음 명령을 사용할 수 있습니다.

git rev-parse --is-inside-work-tree

Git 저장소라면 다음 결과가 나타납니다.

true

.git 디렉터리 존재 여부를 직접 확인할 수도 있습니다.

ls -la

출력에 다음 디렉터리가 있다면 이미 Git 저장소입니다.

.git

7. ROS 2 프로젝트용 .gitignore를 작성합니다

ROS 2 프로젝트를 빌드하면 다음 디렉터리가 자동으로 생성됩니다.

build/
install/
log/

이 디렉터리는 용량이 크고 각 컴퓨터에서 다시 생성할 수 있으므로 GitHub에 올리지 않습니다.

프로젝트 최상위 폴더에서 .gitignore 파일을 생성합니다.

touch .gitignore

VS Code로 엽니다.

code .gitignore

다음 내용을 작성합니다.

# ROS 2 colcon build results
build/
install/
log/

# Python generated files
__pycache__/
*.py[cod]
.pytest_cache/
.coverage

# CMake generated files
CMakeCache.txt
CMakeFiles/
compile_commands.json

# VS Code and IDE settings
.vscode/
.idea/

# Operating system files
.DS_Store
Thumbs.db

# Temporary files
*.tmp
*.swp
*~

# Secret and environment files
.env
.env.*
*.key
*.pem

# ROS bag files
bags/
rosbag/
*.bag
*.db3
*.mcap

# Video and large recording files
*.mp4
*.avi
*.mov

.gitignore는 Git이 Commit에서 제외할 파일과 디렉터리를 지정하는 파일입니다. 팀원도 같은 제외 규칙을 사용해야 하므로 .gitignore 자체는 GitHub에 올리는 것이 좋습니다.

8. GitHub에 올리면 안 되는 파일을 확인합니다

다음 정보는 절대로 GitHub에 올리지 않습니다.

GitHub Personal Access Token
SSH 개인 키
Wi-Fi 비밀번호
서버 접속 비밀번호
API Key
카메라 계정 정보
클라우드 인증 파일
.env 파일
로봇의 개인 네트워크 정보
고객 또는 사용자 개인정보

프로젝트에서 환경 파일을 확인합니다.

find . -maxdepth 3 -name ".env*" -o -name "*.key" -o -name "*.pem"

민감한 문자열을 간단히 검색할 수도 있습니다.

grep -RniE "password|token|secret|api[_-]?key" . \
  --exclude-dir=.git \
  --exclude-dir=build \
  --exclude-dir=install \
  --exclude-dir=log

검색 결과가 나온다고 모두 비밀번호인 것은 아니지만 Commit 전에 반드시 확인해야 합니다.

9. 대용량 파일을 확인합니다

GitHub는 일반 Git 저장소에서 50 MiB를 초과하는 파일에 경고를 표시하고, 100 MiB보다 큰 파일은 Push를 차단합니다. 큰 파일은 Git LFS 또는 별도 저장 공간을 사용하는 것이 적합합니다.

현재 프로젝트에서 50MB보다 큰 파일을 찾습니다.

find . -type f -size +50M \
  -not -path "./.git/*" \
  -not -path "./build/*" \
  -not -path "./install/*" \
  -not -path "./log/*"

TurtleBot3 또는 ROS 2 프로젝트에서는 다음 파일이 자주 문제가 됩니다.

rosbag 파일
카메라 녹화 영상
AI 모델 파일
학습 데이터셋
대용량 지도 파일
실행 로그
압축 파일
Gazebo 모델과 고해상도 mesh

불필요한 파일은 삭제하거나 .gitignore에 추가합니다.

10. 방법 1: GitHub 저장소가 완전히 비어 있는 경우

GitHub 저장소에 README, LICENSE, .gitignore 등 아무 파일도 없다면 현재 프로젝트 폴더에서 바로 연결할 수 있습니다.

GitHub 공식 절차도 로컬 프로젝트 폴더에서 저장소를 초기화하고 파일을 Stage한 다음 Commit과 Push를 수행하는 방식입니다.

1) 프로젝트 폴더에서 Git 저장소를 초기화합니다

cd ~/gazebo_ws
git init -b main

Git 2.28보다 오래된 버전에서 -b 옵션이 동작하지 않는다면 다음 명령을 사용합니다.

git init
git branch -M main

상태를 확인합니다.

git status

다음과 비슷한 내용이 나타납니다.

On branch main

No commits yet

Untracked files:
  .gitignore
  src/

2) 현재 브랜치를 확인합니다

git branch

아직 첫 Commit이 없다면 브랜치 목록이 표시되지 않을 수도 있습니다.

다음 명령으로 현재 브랜치 이름을 확인할 수 있습니다.

git branch --show-current

결과가 다음과 같아야 합니다.

main

3) Commit에 포함할 파일을 확인합니다

먼저 다음 명령을 실행합니다.

git status

.gitignore가 정상적으로 적용되었다면 다음 항목은 표시되지 않아야 합니다.

build/
install/
log/

특정 파일이 무시되는지 확인하려면 다음 명령을 사용할 수 있습니다.

git check-ignore -v build
git check-ignore -v install
git check-ignore -v log

4) 파일을 Stage합니다

모든 파일을 Stage하기 전에 상태를 반드시 확인합니다.

git status

문제가 없다면 다음 명령을 실행합니다.

git add .

git add .은 현재 디렉터리 아래의 변경 파일을 Commit 준비 상태로 만듭니다.

Stage 결과를 확인합니다.

git status

다음과 같이 표시됩니다.

Changes to be committed:
  new file: .gitignore
  new file: README.md
  new file: src/...

Stage된 실제 변경 내용을 확인합니다.

git diff --cached

파일 이름만 확인하려면 다음 명령을 사용합니다.

git diff --cached --name-status

다음 파일이 포함되지 않았는지 다시 확인합니다.

build/
install/
log/
.env
*.key
*.pem
*.db3
*.mcap
대용량 영상

5) 첫 Commit을 생성합니다

git commit -m "chore: initial project source upload"

Commit이 생성되었는지 확인합니다.

git log --oneline

다음과 비슷한 결과가 나타납니다.

a1b2c3d chore: initial project source upload

6) GitHub 저장소 주소를 복사합니다

GitHub 저장소 페이지에서 Code 버튼을 누릅니다.

HTTPS 주소를 복사합니다.

형식은 다음과 같습니다.

https://github.com/hsmaster/gazebo_ws.git

7) 로컬 저장소와 GitHub 저장소를 연결합니다

다음 명령에서 주소를 실제 GitHub 저장소 주소로 바꿉니다.

git remote add origin https://github.com/hsmaster/gazebo_ws.git

origin은 연결한 원격 저장소를 부르는 기본 이름입니다.

GitHub 공식 문서에서도 git remote add 명령에 원격 이름과 저장소 URL을 전달해 연결하도록 안내합니다.

연결 상태를 확인합니다.

git remote -v

정상이라면 다음과 비슷하게 표시됩니다.

origin  https://github.com/USER-NAME/turtlebot3-team-project.git (fetch)
origin  https://github.com/USER-NAME/turtlebot3-team-project.git (push)

8) GitHub에 첫 번째 Push를 수행합니다

git push -u origin main

각 항목의 의미는 다음과 같습니다.

git push
로컬 Commit을 GitHub에 전송

-u
현재 로컬 브랜치와 원격 브랜치의 추적 관계 설정

origin
원격 저장소 이름

main
업로드할 브랜치 이름

첫 번째 Push 이후에는 다음 명령만 사용할 수 있습니다.

git push

11. GitHub 로그인 창이 나타나는 경우

HTTPS 주소를 이용해 Push하면 GitHub 인증이 필요합니다.

GitHub는 Git 명령줄 인증에 일반 계정 비밀번호를 사용하지 않습니다. HTTPS에서는 GitHub CLI, Git Credential Manager, Personal Access Token 등의 인증 방법을 사용하며, VS Code에서는 브라우저 로그인 창이 나타날 수 있습니다.

브라우저 인증 창이 열리면 다음 순서로 진행합니다.

GitHub 계정으로 로그인합니다.
VS Code 또는 Git Credential Manager 권한 요청을 확인합니다.
Authorize를 누릅니다.
2단계 인증을 사용 중이라면 인증 코드를 입력합니다.
터미널로 돌아가 Push 결과를 확인합니다.

Ubuntu에서 GitHub CLI를 사용하는 경우 다음과 같이 인증할 수도 있습니다.

sudo apt install gh
gh auth login

화면 안내에서 일반적으로 다음 항목을 선택합니다.

GitHub.com
HTTPS
Login with a web browser

다음 화면에 인증번호 6자리를 입력창이 출력됩니다. Google Authebticator를 이용하여 github의 Account를 미리 등록해야 합니다. 이 값은 매번 변경되는데 현재 6자리 숫자를 입력하면 아래와 같이 Device Activation 창이 출력됩니다. 여기서 continue 버튼을 클릭합니다.

위의 8자리 숫자를 아래 창에 입력합니다.

다시 업로드를 시도합니다.

git push -u origin main

12. 업로드가 성공했는지 확인합니다

GitHub 저장소 페이지를 새로 고칩니다.

다음 파일이 표시되는지 확인합니다.

.gitignore
README.md
src/
package.xml
CMakeLists.txt
setup.py
launch/
config/

다음 파일이 표시되면 안 됩니다.

build/
install/
log/
.env
*.key
*.pem
rosbag 파일
대용량 영상

터미널에서도 상태를 확인합니다.

git status

정상이라면 다음과 같이 표시됩니다.

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

13. 방법 2: GitHub 저장소에 README가 이미 있는 경우

GitHub 저장소를 생성하면서 다음 항목을 선택했다면 원격 저장소에는 이미 첫 Commit이 존재합니다.

Add a README file
Add .gitignore
Choose a license

이 상태에서 로컬 폴더를 별도로 git init한 후 바로 Push하면 다음 오류가 발생할 수 있습니다.

rejected
non-fast-forward

원격 저장소와 로컬 저장소가 서로 다른 Commit 기록에서 시작했기 때문입니다.

초보자에게 가장 안전한 방법은 다음과 같습니다.

GitHub 저장소 Clone
→ Clone된 폴더에 현재 소스 복사
→ Commit
→ Push

1) 기존 프로젝트를 백업합니다

cd ~
cp -a pyqt_ws pyqt_ws_backup
mv pyqt_ws pyqt_ws_origin

2) GitHub 저장소를 새로운 폴더로 Clone합니다

git clone https://github.com/hsmaster/pyqt_ws.git

Clone한 폴더로 이동합니다.

cd ~/pyqt_ws

원격 연결을 확인합니다.

git remote -v

git clone을 사용하면 GitHub 저장소의 Commit 기록과 브랜치를 내려받고, 원격 저장소가 자동으로 origin이라는 이름으로 연결됩니다.

3) Clone된 폴더에 현재 프로젝트 소스를 복사합니다

파일 탐색기를 이용해 복사해도 됩니다.

터미널에서는 rsync를 이용할 수 있습니다.

rsync -av \
  --exclude='.git/' \
  --exclude='build/' \
  --exclude='install/' \
  --exclude='log/' \
  ~/pyqt_ws_origin/ \
  ~/pyqt_ws/

여기서 중요한 점은 .git 디렉터리를 복사하지 않는 것입니다.

복사가 완료되면 Clone한 폴더로 이동합니다.

cd ~/pyqt_ws

파일을 확인합니다.

ls -la

4) 변경 내용을 확인합니다

git status
git diff

새로 추가된 파일과 수정된 파일이 표시됩니다.

5) 파일을 Stage하고 Commit합니다

git add .
git status
git diff --cached --name-status

문제가 없다면 Commit합니다.

git commit -m "feat: add initial TurtleBot3 project source"

6) GitHub에 Push합니다

git push origin main

이 방법은 GitHub에 존재하던 README Commit 기록을 유지하면서 현재 프로젝트 소스를 추가합니다.