Git: failed to push some refs — що пішло не так

Якби за кожну помилку, яку видає Git, айтівцям давали долар, ринок змінився б дуже драматично. Але раз долар не дають, а помилка залишається — потрібно її виправляти. На щастя, це далеко не найкритичніша проблема і фікситься вона легко.

В цій короткій статті розберемо, що таке failed to push some refs, звідки ця помилка береться, як її пофіксити, а чого робити точно не варто.  

1. Що означає помилка failed to push some refs

Помилка failed to push some refs з’являється під час виконання git push — у терміналі або в GUI-клієнтах (GitHub Desktop, SourceTree, VS Code). Вона означає, що Git відмовився відправляти ваші коміти на віддалений репозиторій.

Найчастіше це трапляється, коли:

• Ви працюєте в команді й хтось уже запушив зміни в ту саму гілку
• Ви робили rebase, змінивши історію комітів
• Ви намагаєтесь пушити напряму в захищену гілку (main, develop)

Але чому Git блокує push?

Якщо коротко, це відбувається через те, що ваша локальна історія комітів не відповідає віддаленій.

Git працює з історією змін як з ланцюжком комітів. Якщо у віддаленій гілці є коміти, яких немає у вас локально, Git не може просто додати ваші зміни зверху — це призвело б до втрати частини історії.

Тому Git перевіряє, чи є ваш push fast-forward, і якщо ні — блокує push і показує failed to push some refs. Це захисний механізм, а не помилка у прямому сенсі. Git таким чином каже:

2. Найпоширеніші причини

У більшості випадків failed to push some refs виникає через кілька типових сценаріїв. Ось ті, що трапляються найчастіше.

• У віддаленій гілці є коміти, яких немає локально

Це найкласичніша причина. Хтось із команди вже запушив зміни в ту саму гілку, а ви про це ще не знаєте. В результаті локальна гілка «відстає» від remote, а Git не дозволяє push, щоб не перезаписати чужу роботу. 

Зазвичай у повідомленні Git прямо пише щось на кшталт:

Updates were rejected because the remote contains work that you do not have locally.

• Push у захищену (protected) гілку

У багатьох репозиторіях гілки main, master, develop захищені від прямого push. У цьому випадку: Git локально може бути «задоволений» історією, але сервер відхиляє push політикою доступу.

• Неправильна гілка або upstream

Іноді проблема не в комітах, а в тому, куди саме ви пушите. Локальна гілка може бути не прив’язана до жодної remote-гілки. Альтернативно, можливо, ви пушите в origin/main, а реально працювали в feature/login. У таких випадках Git просто не розуміє, куди коректно відправляти зміни.

• Конфлікти після rebase або merge

Після rebase історія комітів змінюється. Для Git це виглядає так, ніби ваші коміти — інші, навіть якщо код майже не змінився. Якщо гілка вже існує на remote і ви зробили rebase локально, звичайний git push буде заблокований, бо історії більше не збігаються.

4 команди для швидкої діагностики

Перш ніж щось «лікувати», варто зрозуміти, що саме не так. Зазвичай достатньо 4 команд, щоби побачити повну картину і не діяти навмання.

• git status

Ця команда дає інформацію про базові речі: в якій ви гілці, чи є незакомічені зміни, чи відстає або випереджає локальна гілка remote. Часто Git прямо тут підказує проблему.

• git branch -vv

Ця команда показує всі локальні гілки, до якої remote-гілки вони прив’язані та чи є розбіжності по комітах. Саме тут легко помітити, якщо upstream взагалі не заданий або гілка прив’язана не до тієї remote-гілки.

• git fetch

Команда fetch не змінює ваш код, але оновлює інформацію про віддалений репозиторій. Це важливо, бо без нього ви можете дивитись на застарілу картину, а Git думатиме, що все ок, поки remote рухатиметься вперед. Завжди робіть git fetch перед діагностикою — це безпечно і швидко.

• git log --oneline --graph --decorate --all

Це найбільш наочний інструмент. Він дозволяє побачити, де знаходиться ваша гілка відносно origin, зрозуміти, чи є розходження історії та одразу помітити наслідки merge або rebase.

Сценарії розв’язання

Remote має нові коміти

Якщо віддалена гілка пішла вперед, спочатку потрібно підтягнути ці зміни.

Рекомендований варіант:

git pull --rebase

Що відбувається:

• Git забирає нові коміти з remote
• Тимчасово «знімає» ваші локальні коміти
• Накладає їх поверх актуальної історії

В результаті ви отримуєте чисту лінійну історію без зайвих merge-комітів.

Альтернативно, якщо ви не використовуєте rebase, можна виконати: 

git pull

В цьому випадку Git зробить merge, що теж валідно, але історія стане розгалуженою.

Після цього git push зазвичай проходить без проблем.

Push у protected branch

У захищені гілки не можна пушити напряму, бо це захищає історію від випадкових force push, змушує проходити code review та зменшує ризик зламати продакшн.

Натомість краще: 

1. Створити feature-гілку:

git checkout -b feature/my-change

2. Запушити її:

git push -u origin feature/my-change

3. Створити Pull Request/Merge Request у main або develop.

Неправильний upstream

Спочатку перевірте, чи взагалі є upstream:

git branch -vv

Якщо гілка не прив’язана або прив’язана неправильно — Git не знає, куди пушити.

Як задати upstream явно:

git push -u origin branch-name

Після цього:

• git push і git pull працюватимуть без додаткових параметрів
• Git чітко знатиме, з якою remote-гілкою синхронізуватись

Після rebase Git не дає пушити

Після rebase змінюються хеші комітів. Для remote це виглядає так, ніби ви намагаєтесь переписати історію. Тому звичайний push блокується.

Команда force push допустима, якщо ви працюєте у своїй feature-гілці, ніхто інший її не використовує, і ви розумієте наслідки.

У такому випадку використовуйте безпечніший варіант:

git push --force-with-lease

Він перевіряє, що remote не змінився з моменту вашого останнього fetch.

Конфлікти

Їх можна розпізнати за кількома ознаками:

• Git зупиняє pull, merge або rebase
• у файлах з’являються маркери <<<<<<<, =======, >>>>>>>

Щоб розвʼязати конфлікти:

1. Відкрийте файли з конфліктами

2. Вручну оберіть правильний варіант коду

3. Видаліть конфліктні маркери

4. Додайте файли:

git add .

5. Завершіть процес:

• Після merge: git commit
• Після rebase: git rebase --continue

Після цього push знову стане можливим.

Чого не варто робити

Коли git push не працює, дуже легко зробити щось імпульсивне — і створити проблему вже не тільки собі, але й усій команді. А отже, є кілька типових помилок, яких краще уникати.

Сліпий git push --force

Команда force push — не зло сама по собі, але використовувати її без розуміння контексту небезпечно. Ви можете перезаписати чужі коміти, зламати історію гілки та змусити команду вручну відновлювати зміни.

Якщо вже і форсити — то тільки усвідомлено, і бажано через --force-with-lease. В усіх інших випадках спочатку варто розібратися, чому Git блокує push.

Видалення гілки «бо не пушиться»

Ідея «видалю гілку і створю заново» виглядає швидким рішенням, але часто призводить до втрати локальних комітів, ускладнює відновлення історії та маскує реальну причину проблеми.

Якщо гілка не пушиться — це симптом, а не причина. Git майже завжди дає можливість синхронізувати історію без радикальних кроків.

Rebase shared-гілок без розуміння наслідків

Команда rebase переписує історію. Якщо робити це в гілках, якими користуються інші (main, develop, спільні feature-гілки), то це породить лише більше хаосу.

У ваших колег можуть зʼявитись дивні конфлікти, коміти можуть зникати або дублюватись, а загальна недовіра до репозиторію зростатиме. Тому завжди варто слідувати золотому правилу:

• rebase — для локальних та особистих гілок
• shared-гілки — тільки через merge або PR

У більшості випадків failed to push some refs — це не проблема, яку треба «продавити», а підказка від Git. Якщо її проігнорувати — Git все одно нагадає про себе, але вже у значно болючіший спосіб.