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

by

14. 방법 3: 여러 명이 사용하는 팀 저장소에 업로드하는 경우

팀원들이 이미 사용 중인 저장소라면 main 브랜치에 직접 Push하지 않는 것이 좋습니다.

저장소의 main 브랜치가 보호되어 있다면 직접 Push가 차단되고 Pull Request와 리뷰가 요구될 수도 있습니다.

권장 순서는 다음과 같습니다.

저장소 Clone
→ 작업 브랜치 생성
→ 현재 소스 복사
→ Commit
→ 작업 브랜치 Push
→ Pull Request 생성

1) 저장소를 Clone합니다

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

2) 작업 브랜치를 생성합니다

cd ~/pyqt_ws
git switch -c feature/initial-source-upload

현재 브랜치를 확인합니다.

git branch

다음처럼 작업 브랜치 앞에 *가 표시되어야 합니다.

  main
* feature/initial-source-upload

3) 현재 소스를 복사합니다

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

4) 변경 내용을 Commit합니다

git status
git add .
git diff --cached --name-status
git commit -m "feat: upload initial pyqt_ws source"

5) 작업 브랜치를 Push합니다

git push -u origin feature/initial-source-upload

6) Pull Request를 생성합니다

GitHub 저장소 페이지를 열면 다음 버튼이 나타날 수 있습니다.

Compare & pull request

다음과 같이 설정합니다.

base: main
compare: feature/initial-source-upload

Pull Request 제목 예시는 다음과 같습니다.

feat: pyqt_ws 프로젝트 초기 소스 업로드

설명에는 다음 내용을 작성합니다.

## 1. 작업 내용

현재까지 개발한 TurtleBot3 Burger 프로젝트 소스를 업로드했습니다.

## 2. 포함된 내용

1. ROS 2 패키지
2. launch 파일
3. parameter 설정 파일
4. TurtleBot3 제어 노드
5. README 문서
6. ROS 2용 .gitignore

## 3. 제외한 내용

1. build
2. install
3. log
4. rosbag
5. 개인 환경 설정
6. 인증 정보

## 4. 확인 사항

1. colcon build 확인
2. package.xml 의존성 확인
3. launch 파일 실행 확인

다른 팀원이 내용을 확인한 후 main에 Merge합니다.

15. 현재 프로젝트가 이미 Git 저장소인 경우

현재 폴더에 이미 .git 디렉터리가 있다면 다시 git init할 필요가 없습니다.

현재 상태부터 확인합니다.

cd ~/odom_path_viewer
git status
git branch
git log --oneline --all --decorate -10

원격 저장소 연결을 확인합니다.

git remote -v

1) origin이 없는 경우

결과가 아무것도 나오지 않는다면 GitHub 저장소를 연결합니다.

git remote add origin \
  https://github.com/USER-NAME/turtlebot3-team-project.git

확인합니다.

git remote -v

2) origin 주소가 잘못된 경우

현재 주소를 확인합니다.

git remote -v

기존 origin의 주소를 변경합니다.

git remote set-url origin \
  https://github.com/USER-NAME/turtlebot3-team-project.git

다시 확인합니다.

git remote -v

3) GitHub 저장소가 비어 있다면 Push합니다

git branch -M main
git push -u origin main

4) GitHub 저장소에 이미 Commit이 있다면 주의합니다

원격 저장소에 README 등의 Commit이 존재한다면 무조건 Push하지 않습니다.

먼저 원격 내용을 확인합니다.

git fetch origin
git branch -a
git log --oneline --all --graph --decorate -15

로컬과 원격이 같은 Git 기록을 공유한다면 다음처럼 병합할 수 있습니다.

git merge origin/main

하지만 로컬과 원격이 각각 따로 생성된 저장소라면 서로 관련 없는 기록일 수 있습니다.

초보자는 이 경우 강제로 기록을 합치기보다 다음 방법이 안전합니다.

  1. GitHub 저장소를 새로운 폴더에 Clone합니다.
  2. 기존 프로젝트 파일만 Clone된 폴더에 복사합니다.
  3. Commit 후 Push합니다.

git push --force로 원격 README를 덮어쓰는 방식은 사용하지 않습니다.

16. VS Code를 이용해 업로드하는 방법

VS Code에서는 Stage, Commit, Push 작업을 화면으로 처리할 수 있습니다.

단, 이미 GitHub에 저장소를 만들어 놓았다면 Publish to GitHub 버튼을 바로 누르지 않는 것이 좋습니다.

VS Code의 Publish to GitHub 기능은 새로운 GitHub 저장소를 생성하고 원격 저장소를 연결한 후 Commit을 Push하는 기능입니다. 이미 만들어 놓은 저장소에 연결하려는 상황과는 다를 수 있습니다.

1) GitHub 저장소가 비어 있는 경우

VS Code에서 현재 프로젝트 폴더를 엽니다.

cd ~/pyqt_study
code .

다음 순서로 진행합니다.

a. 왼쪽의 Source Control 아이콘을 누릅니다.

b. Initialize Repository를 누릅니다.

c. .gitignore를 먼저 작성합니다.

d. Changes 목록을 확인합니다.

e. 필요한 파일 오른쪽의 + 버튼을 누릅니다.

위와 같이 아무것도 stage하지 않고 커밋해도 다음 단계에서 모두를 선택할 수 있습니다.

f. Commit 메시지를 입력합니다.

g. Commit 버튼을 누릅니다.

위의 메세지는 “스테이징된 변경 내용이 없습니다.
모든 변경 내용을 스테이징하고 직접 커밋하시겠습니까?” 입니다. stage 단계에서 파일을 하나도 선택하지 않아서 나타나는 메세지 입니다. 여기서 Yes 또는 Always를 선택하면 모든 변경 내용이 자동으로 Stage되어 Commit될 수 있습니다. 이 선택은 CLI 명령인 “git add .”와 동일합니다.

그다음 VS Code 터미널에서 원격 저장소를 연결합니다.

git branch -M main
git remote add origin https://github.com/hsmaster/pyqt_study.git
git push -u origin main

첫 연결이 끝나면 이후부터 VS Code Source Control 메뉴의 Push를 사용할 수 있습니다.

2) GitHub 저장소에 README가 이미 있는 경우

VS Code에서 다음 순서로 Clone합니다.

a. Ctrl + Shift + P를 누릅니다.

b. Git: Clone을 입력합니다.

c. GitHub 저장소 주소를 붙여 넣습니다.

d. 저장할 폴더를 선택합니다.

e. Clone된 저장소를 엽니다.

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

rsync -av \
  --exclude='.git/' \
  --exclude='build/' \
  --exclude='install/' \
  --exclude='log/' \
  ~/tb3_ws_origin/ \
  ~/tb3_ws/

g. Source Control에서 변경 파일을 확인합니다.

h. 필요한 파일을 Stage합니다.

위와 같이 아무것도 stage하지 않고 커밋해도 다음 단계에서 모두를 선택할 수 있습니다.

i. Commit 메시지를 작성합니다.

j. Commit합니다.

위의 메세지는 “스테이징된 변경 내용이 없습니다.
모든 변경 내용을 스테이징하고 직접 커밋하시겠습니까?” 입니다. stage 단계에서 파일을 하나도 선택하지 않아서 나타나는 메세지 입니다. 여기서 Yes 또는 Always를 선택하면 모든 변경 내용이 자동으로 Stage되어 Commit될 수 있습니다. 이 선택은 CLI 명령인 “git add .”와 동일합니다.

k. Push를 실행합니다.

push가 완료된 상태입니다.

VS Code에서 Clone하면 원격 저장소의 브랜치와 Commit 기록이 함께 내려오고 origin도 자동으로 설정됩니다.

3) VS Code에서 Stage하기

Source Control 화면은 다음 단축키로 열 수 있습니다.

Ctrl + Shift + G

Changes 목록에서 파일을 선택하면 수정 전후 내용을 비교할 수 있습니다.

파일 오른쪽의 + 버튼을 누르면 Stage됩니다.

모든 파일을 한 번에 Stage하려면 Changes 제목 오른쪽의 + 버튼을 누릅니다.

Stage 후에는 Staged Changes 목록을 다시 확인합니다.

4) VS Code에서 Commit하기

Source Control 위쪽 입력 칸에 Commit 메시지를 작성합니다.

feat: upload initial tb3_ws project source

Commit 버튼을 누릅니다.

5) VS Code에서 Push하기

Source Control의 ... 메뉴에서 다음 항목을 선택합니다.

Push

새 브랜치라면 다음 버튼이 표시될 수 있습니다.

Publish Branch

이미 원격 저장소가 연결되어 있으면 Publish Branch는 현재 브랜치를 GitHub에 올리고 추적 관계를 설정합니다.

VS Code의 Push는 로컬 Commit을 원격 브랜치에 업로드하며, Pull은 원격 Commit을 내려받아 현재 브랜치에 반영합니다.

17. 업로드 후 소스를 수정해서 다시 올리는 방법

최초 업로드가 끝난 후에는 매번 git init이나 git remote add를 실행하지 않습니다.

일반적인 수정 절차는 다음과 같습니다.

cd ~/ros2_ws/turtlebot3_team_project
git status
git diff
git add 수정한파일
git commit -m "feat: 작업 내용"
git push

예를 들어 navigation 노드를 수정했다면 다음과 같이 진행합니다.

git status
git diff src/team_navigation/src/navigation_node.cpp
git add src/team_navigation/src/navigation_node.cpp
git commit -m "fix: waypoint 도착 판정 조건 수정"
git push

팀 프로젝트에서는 작업 전에 최신 코드를 먼저 받습니다.

git switch main
git pull --ff-only origin main
git switch -c feature/작업이름

작업 후에는 브랜치를 Push합니다.

git push -u origin feature/작업이름

그다음 Pull Request를 생성합니다.

18. 자주 발생하는 오류와 해결 방법

1) remote origin already exists

오류 메시지는 다음과 같습니다.

fatal: remote origin already exists

이미 origin이라는 원격 저장소가 연결되어 있다는 뜻입니다.

현재 연결을 확인합니다.

git remote -v

주소가 맞다면 git remote add를 다시 실행할 필요가 없습니다.

주소가 틀렸다면 변경합니다.

git remote set-url origin \
  https://github.com/USER-NAME/turtlebot3-team-project.git

2) src refspec main does not match any

오류 메시지는 다음과 같습니다.

error: src refspec main does not match any

주요 원인은 다음과 같습니다.

  1. 아직 Commit을 한 번도 만들지 않았습니다.
  2. 현재 브랜치 이름이 main이 아닙니다.
  3. Stage만 하고 Commit하지 않았습니다.

현재 상태를 확인합니다.

git status
git branch --show-current
git log --oneline

Commit이 없다면 다음과 같이 진행합니다.

git add .
git commit -m "chore: initial project source upload"
git branch -M main
git push -u origin main

3) non-fast-forward 오류

오류 메시지는 다음과 같습니다.

! [rejected] main -> main (non-fast-forward)
error: failed to push some refs

GitHub에 로컬에는 없는 Commit이 존재하는 상태입니다.

다른 팀원이 먼저 Push했거나 GitHub 저장소를 만들 때 README가 추가된 경우 발생할 수 있습니다.

GitHub는 원격 변경 내용을 먼저 가져와 병합한 뒤 Push하도록 안내합니다.

같은 저장소 기록을 공유하는 일반적인 경우에는 다음과 같이 처리합니다.

git fetch origin
git merge origin/main
git push origin main

로컬과 원격이 별도로 생성된 저장소라면 Clone 후 파일 복사 방식을 사용하는 것이 안전합니다.

다음 명령으로 강제 Push하지 않습니다.

git push --force

4) repository not found

오류 메시지는 다음과 같습니다.

remote: Repository not found.
fatal: repository not found

다음 내용을 확인합니다.

  1. GitHub 저장소 주소가 정확한가
  2. 저장소 이름의 대소문자가 정확한가
  3. 로그인한 GitHub 계정이 맞는가
  4. 비공개 저장소에 접근 권한이 있는가
  5. Collaborator 초대를 수락했는가

원격 주소를 확인합니다.

git remote -v

잘못되었다면 수정합니다.

git remote set-url origin \
  https://github.com/USER-NAME/REPOSITORY-NAME.git

5) Permission denied 오류

오류 메시지는 다음과 비슷합니다.

Permission to USER/REPOSITORY denied

현재 GitHub 계정에 쓰기 권한이 없을 가능성이 큽니다.

팀장에게 다음 사항을 확인합니다.

  1. Collaborator로 초대되었는가
  2. 초대를 수락했는가
  3. 올바른 GitHub 계정으로 로그인했는가
  4. 해당 저장소에 Write 권한이 있는가

GitHub 저장소 소유자가 사용자를 Collaborator 또는 쓰기 권한이 있는 팀에 추가해야 Push할 수 있습니다.

6) authentication failed

일반 GitHub 계정 비밀번호를 Git 터미널에 입력하면 인증이 실패할 수 있습니다.

GitHub는 Git 명령줄에서 비밀번호 기반 인증을 제거했으므로 다음 중 하나를 사용해야 합니다.

  1. VS Code 브라우저 로그인
  2. GitHub CLI
  3. Git Credential Manager
  4. Personal Access Token
  5. SSH Key

GitHub CLI를 사용하는 경우 다음 명령을 실행합니다.

gh auth login

7) 파일이 너무 크다는 오류

오류 메시지는 다음과 비슷합니다.

File ... is 120 MB
This exceeds GitHub's file size limit of 100 MB

다음 파일을 확인합니다.

find . -type f -size +50M -not -path "./.git/*"

불필요한 파일이라면 .gitignore에 추가하고 Stage에서 제거합니다.

git restore --staged 경로/파일이름

이미 Git이 추적하고 있다면 다음 명령으로 Git 추적에서 제외합니다.

git rm --cached 경로/파일이름

파일은 로컬에 남고 Git 추적 대상에서만 제거됩니다.

100 MiB보다 큰 파일이 반드시 필요하다면 Git LFS를 검토해야 합니다.

8) build, install, log가 Stage에 들어간 경우

먼저 .gitignore에 다음 내용을 추가합니다.

build/
install/
log/

아직 Commit하지 않았다면 Stage에서 제거합니다.

git restore --staged build install log

이미 Git이 추적 중이라면 다음과 같이 처리합니다.

git rm -r --cached build install log
git add .gitignore
git commit -m "chore: exclude ROS 2 build artifacts"

9) nothing to commit

다음 메시지는 오류가 아닙니다.

nothing to commit, working tree clean

현재 Commit할 변경 사항이 없다는 뜻입니다.

다음 명령으로 상태를 다시 확인합니다.

git status

19. 사용하면 위험한 명령

초보자는 다음 명령을 함부로 사용하지 않습니다.

git push --force
git push -f
git reset --hard
git clean -fd
rm -rf .git

각 명령은 다음 위험이 있습니다.

  1. git push --force는 원격 저장소의 Commit 기록을 덮어쓸 수 있습니다.
  2. git reset --hard는 Commit하지 않은 수정 내용을 삭제할 수 있습니다.
  3. git clean -fd는 Git이 추적하지 않는 파일과 디렉터리를 삭제할 수 있습니다.
  4. rm -rf .git은 현재 프로젝트의 Git 기록과 설정을 제거합니다.

명령의 결과를 정확히 모른다면 먼저 다음 명령을 실행합니다.

git status
git remote -v
git branch -a
git log --oneline --all --graph --decorate -10

20. 최초 업로드용 전체 명령 모음

GitHub 저장소가 완전히 비어 있다는 전제에서 사용할 수 있는 명령입니다.

cd ~/ros2_ws/turtlebot3_team_project

git init -b main

git status

git add .

git diff --cached --name-status

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

git remote add origin \
  https://github.com/USER-NAME/turtlebot3-team-project.git

git remote -v

git push -u origin main

git status

실행 전에 반드시 .gitignore를 먼저 작성해야 합니다.

21. README가 있는 저장소에 업로드하는 전체 명령 모음

cd ~/ros2_ws

git clone \
  https://github.com/USER-NAME/turtlebot3-team-project.git \
  turtlebot3_team_project_github

rsync -av \
  --exclude='.git/' \
  --exclude='build/' \
  --exclude='install/' \
  --exclude='log/' \
  ~/ros2_ws/turtlebot3_team_project/ \
  ~/ros2_ws/turtlebot3_team_project_github/

cd ~/ros2_ws/turtlebot3_team_project_github

git status

git add .

git diff --cached --name-status

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

git push origin main

git status

22. 팀 저장소에 브랜치로 업로드하는 전체 명령 모음

cd ~/ros2_ws

git clone \
  https://github.com/USER-NAME/turtlebot3-team-project.git \
  turtlebot3_team_project_github

cd ~/ros2_ws/turtlebot3_team_project_github

git switch -c feature/initial-source-upload

rsync -av \
  --exclude='.git/' \
  --exclude='build/' \
  --exclude='install/' \
  --exclude='log/' \
  ~/ros2_ws/turtlebot3_team_project/ \
  ~/ros2_ws/turtlebot3_team_project_github/

git status

git add .

git diff --cached --name-status

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

git push -u origin feature/initial-source-upload

Push가 끝나면 GitHub에서 Pull Request를 생성합니다.

Leave a Comment