# Tracking branch

_Удалённые репозитории · GitLab Knowledge Base_

**TL;DR:** Связь между локальной веткой и удалённой: «эта моя ветка
следит за этой удалённой». Включает поведение `git pull`/`push`
без аргументов и `git status` сообщения вида «ahead 3, behind 2».


Tracking branch (она же «upstream branch») - это указатель внутри
локальной ветки на «свою» удалённую. Хранится в `.git/config`:

```
[branch "main"]
    remote = origin
    merge = refs/heads/main
```

Это значит: «локальная main привязана к origin/main». Что это даёт:

- `git pull` без аргументов знает, откуда тянуть.
- `git push` без аргументов знает, куда пушить.
- `git status` сравнивает с этой удалённой: «Your branch is ahead
  by 3 commits».
- В `git branch -vv` рядом с веткой видно её upstream.

## Как устанавливается

Три способа:

```bash
# 1. При первом push
git push -u origin feature
# эквивалент: git push --set-upstream origin feature

# 2. Постфактум для существующей ветки
git branch --set-upstream-to=origin/feature feature

# 3. При switch -c из remote
git switch -c feature origin/feature
```

После любого из этих способов ветка «привязана», и дальнейшие
`git pull` / `git push` работают без аргументов.

## remote-tracking branch - это отдельное

Не путай:

  - **Tracking branch** - локальная ветка, помнящая свою remote
  (упомянуто выше).
  - **Remote-tracking branch** - `origin/main`, `origin/feature/x`.
  Это локальные refs, отражающие состояние remote (см. [fetch](/courses/git/kb/fetch.md)).

Их связь:
```
локальная main  ─ tracks ─→  origin/main (remote-tracking branch)
                                     ↑
                                     fetch обновляет это
```

## Что показывает git status

```
On branch feature
Your branch is ahead of 'origin/feature' by 2 commits.
```

Это значит:
- У тебя есть 2 коммита, которых нет в `origin/feature`.
- Нужно push'нуть.

```
Your branch is behind 'origin/feature' by 3 commits.
```

- На remote есть 3 коммита, которых у тебя нет.
- Нужно pull или fetch.

```
Your branch and 'origin/feature' have diverged,
and have 2 and 3 different commits each, respectively.
```

- И у тебя, и на remote есть свои коммиты после общего предка.
- Нужно решать: merge, rebase или нагнать чужие и переписать свои.

## Без tracking

Если у локальной ветки нет upstream:

```bash
git push
# fatal: The current branch feature has no upstream branch.
# To push the current branch and set the remote as upstream, use
#     git push --set-upstream origin feature
```

Это специально: Git не угадывает, куда пушить новую ветку. Нужно
явно сказать `-u origin feature`.

## Подводные камни

- **Tracking теряется при переименовании remote.** Если сделать
  `git remote rename origin foo`, у локальных веток `branch.X.remote
  = origin` останется, и pull/push сломаются. `git remote rename`
  обычно это правит, но проверь после.
- **«Ghost» tracking после удаления remote-ветки.** Если ветку на
  remote удалили, локальный tracking остаётся «привязан» к
  несуществующей. `git fetch --prune` убирает мёртвые refs.
- **Конфиг отдельно от состояния.** В `.git/config` пишется, кому
  тебя пушить. А actual SHA лежит в `refs/remotes/origin/<branch>`.
  Если refs устарели - `git fetch`.


## Команды

```bash
git push -u origin feature
```
Установить tracking при первом push

```bash
git branch --set-upstream-to=origin/dev
```
Привязать существующую ветку к origin/dev

```bash
git branch -vv
```
Показать все локальные ветки с их upstream

```bash
git status
```
Видит tracking - пишет 'ahead N / behind M'


## См. также

- [git push](/courses/git/kb/push.md)
- [git pull](/courses/git/kb/pull.md)
- [git fetch](/courses/git/kb/fetch.md)
- [git remote](/courses/git/kb/remote-cmd.md)