Cách khắc phục lỗi Git: 'src refspec main does not match any'

Tình huống

Bạn vừa thiết lập một repository mới trên GitHub hoặc GitLab. Bạn đã làm theo các bước cài đặt, thêm URL remote và thử gửi code lên cloud bằng lệnh git push origin main. Thay vì tải lên thành công, bạn lại thấy một thông báo lỗi hai dòng gây khó chịu.

error: src refspec main does not match any
error: failed to push some refs to 'https://github.com/user/repo.git'

Đây là một trở ngại phổ biến, đặc biệt là với các dự án mới. Điều này xảy ra vì Git đang tìm kiếm một nhánh (branch) về mặt kỹ thuật là chưa tồn tại.

Tại sao lỗi này xảy ra

Thông báo "src refspec main does not match any" là cách Git báo rằng nó không tìm thấy nhánh local nào tên là "main" để đẩy lên. Điều này thường do ba vấn đề cụ thể sau:

Repository của bạn đang trống: Bạn đã khởi tạo Git nhưng chưa thực hiện commit nào. Git không thực sự tạo nhánh cho đến khi nó có ít nhất một bản chụp (snapshot) mã nguồn của bạn.
Sự khác biệt giữa "Master" và "Main": Các phiên bản Git cũ mặc định dùng master, trong khi GitHub đã chuyển mặc định sang main vào tháng 10 năm 2020. Có thể bạn đang làm việc trên master nhưng lại cố gắng push lên main.
Lỗi đánh máy cơ bản: Git phân biệt chữ hoa chữ thường. Nếu nhánh của bạn tên là Main và bạn gõ main, lệnh sẽ thất bại.

Cách khắc phục

1. Thực hiện commit đầu tiên

Nếu bạn chưa commit bất kỳ tệp nào, nhánh main của bạn chưa tồn tại. Bạn không thể push một thứ không tồn tại. Hãy kiểm tra trạng thái trước.

git status

Nếu nó báo "nothing to commit" (không có gì để commit), hãy thêm các tệp của bạn và tạo một điểm bắt đầu:

git add .
git commit -m "Commit đầu tiên"

Bây giờ, hãy thử lại lệnh push. Nó sẽ hoạt động.

2. Đồng bộ tên nhánh

Kiểm tra xem nhánh local của bạn thực sự tên là gì bằng cách chạy git branch. Nếu bạn thấy * master, nhưng bạn đang cố push lên main, bạn có hai lựa chọn.

Lựa chọn A: Đổi tên nhánh local (Khuyên dùng)

Để nhất quán với các tiêu chuẩn hiện đại, hãy đổi tên nhánh master ở local thành main. Sử dụng cờ -M để buộc đổi tên ngay cả khi bạn không ở trên nhánh đó:

git branch -M main
git push -u origin main

Cờ -u là một cứu cánh. Nó liên kết nhánh local của bạn với nhánh remote để sau này bạn chỉ cần gõ git push.

Lựa chọn B: Push nhánh hiện tại như vốn có

Nếu bạn muốn giữ tên master, chỉ cần thay đổi lệnh push cho khớp với tên ở local:

git push origin master

3. Kiểm tra lỗi chính tả

Chạy git branch và quan sát kỹ kết quả. Nếu tên nhánh là Main hoặc dev, lệnh push của bạn phải khớp chính xác. Git sẽ không tự đoán ý bạn đâu.

Xác nhận khắc phục thành công

Làm sao để biết đã thành công? Chạy git status lần cuối. Bạn sẽ thấy thông báo Your branch is up to date with 'origin/main'.

Mở trình duyệt và tải lại trang repository trên GitHub. Các tệp của bạn bây giờ sẽ hiển thị và menu thả xuống của nhánh sẽ hiển thị đúng main cùng với lịch sử commit gần đây.

Danh sách kiểm tra nhanh

Bạn đã chạy git commit chưa? (Một nhánh cần ít nhất một commit để tồn tại).
Lệnh git branch có hiển thị cùng tên với nhánh bạn đang cố push không?
Bạn có đang sử dụng lệnh -M main để sửa xung đột đặt tên master/main không?