mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Mintlify Agent
260 lines
4.2 KiB
Plaintext
260 lines
4.2 KiB
Plaintext
---
|
|
title: git checkout
|
|
description: Switch branches or restore working tree files
|
|
---
|
|
|
|
Switch between branches or restore files to a previous state.
|
|
|
|
## Syntax
|
|
|
|
```bash
|
|
git checkout [options] <branch>
|
|
git checkout [options] <commit>
|
|
git checkout [options] -- <file>
|
|
```
|
|
|
|
## Description
|
|
|
|
`git checkout` serves two main purposes: switching between branches and restoring files. It updates your working directory to match the specified branch or commit.
|
|
|
|
<Note>
|
|
Git 2.23 introduced `git switch` and `git restore` as more intuitive alternatives to `git checkout`.
|
|
</Note>
|
|
|
|
## Common usage
|
|
|
|
Switch to an existing branch:
|
|
|
|
```bash
|
|
git checkout branch-name
|
|
```
|
|
|
|
Create and switch to a new branch:
|
|
|
|
```bash
|
|
git checkout -b new-branch
|
|
```
|
|
|
|
Restore a file to its last committed state:
|
|
|
|
```bash
|
|
git checkout -- filename.txt
|
|
```
|
|
|
|
## Options
|
|
|
|
<ParamField path="-b" type="string">
|
|
Create a new branch and switch to it
|
|
|
|
```bash
|
|
git checkout -b feature-branch
|
|
```
|
|
</ParamField>
|
|
|
|
<ParamField path="-B" type="string">
|
|
Create or reset a branch and switch to it
|
|
</ParamField>
|
|
|
|
<ParamField path="--" type="flag">
|
|
Separator for disambiguating file paths from branch names
|
|
|
|
```bash
|
|
git checkout -- file.txt
|
|
```
|
|
</ParamField>
|
|
|
|
<ParamField path="-f, --force" type="flag">
|
|
Force checkout, discarding local changes
|
|
</ParamField>
|
|
|
|
<ParamField path="-t, --track" type="flag">
|
|
Create a new branch tracking a remote branch
|
|
|
|
```bash
|
|
git checkout -t origin/feature-branch
|
|
```
|
|
</ParamField>
|
|
|
|
## Examples
|
|
|
|
### Switch branches
|
|
|
|
```bash
|
|
# Switch to existing branch
|
|
git checkout main
|
|
|
|
# Switch to remote branch
|
|
git checkout origin/feature-branch
|
|
```
|
|
|
|
### Create new branch
|
|
|
|
```bash
|
|
# Create and switch
|
|
git checkout -b new-feature
|
|
|
|
# Create from specific commit
|
|
git checkout -b hotfix abc123
|
|
```
|
|
|
|
### Restore files
|
|
|
|
```bash
|
|
# Restore one file
|
|
git checkout -- README.md
|
|
|
|
# Restore all files
|
|
git checkout -- .
|
|
|
|
# Restore from specific commit
|
|
git checkout abc123 -- file.txt
|
|
```
|
|
|
|
### Checkout specific commit
|
|
|
|
```bash
|
|
# Detached HEAD state
|
|
git checkout abc123
|
|
|
|
# View specific commit without changing branch
|
|
git checkout tags/v1.0
|
|
```
|
|
|
|
## Modern alternatives
|
|
|
|
Git 2.23+ provides clearer commands:
|
|
|
|
### git switch
|
|
|
|
For changing branches:
|
|
|
|
```bash
|
|
# Instead of: git checkout main
|
|
git switch main
|
|
|
|
# Instead of: git checkout -b new-feature
|
|
git switch -c new-feature
|
|
```
|
|
|
|
### git restore
|
|
|
|
For restoring files:
|
|
|
|
```bash
|
|
# Instead of: git checkout -- file.txt
|
|
git restore file.txt
|
|
|
|
# Restore from specific commit
|
|
git restore --source=abc123 file.txt
|
|
```
|
|
|
|
## Common workflows
|
|
|
|
### Feature branch workflow
|
|
|
|
```bash
|
|
# Create feature branch
|
|
git checkout -b feature/new-feature
|
|
|
|
# Work on feature...
|
|
git add .
|
|
git commit -m "Add feature"
|
|
|
|
# Switch back to main
|
|
git checkout main
|
|
```
|
|
|
|
### Discard local changes
|
|
|
|
```bash
|
|
# Discard changes in one file
|
|
git checkout -- file.txt
|
|
|
|
# Discard all changes
|
|
git checkout -- .
|
|
```
|
|
|
|
### Review old code
|
|
|
|
```bash
|
|
# Checkout specific commit
|
|
git checkout abc123
|
|
|
|
# Look around...
|
|
|
|
# Return to branch
|
|
git checkout main
|
|
```
|
|
|
|
### Pull remote branch
|
|
|
|
```bash
|
|
# Track and checkout remote branch
|
|
git checkout -t origin/feature-branch
|
|
```
|
|
|
|
## Detached HEAD state
|
|
|
|
Checking out a commit puts you in "detached HEAD" state:
|
|
|
|
```bash
|
|
git checkout abc123
|
|
```
|
|
|
|
You're not on any branch. To save work:
|
|
|
|
```bash
|
|
# Create a branch from here
|
|
git checkout -b new-branch-name
|
|
```
|
|
|
|
Or return to a branch:
|
|
|
|
```bash
|
|
git checkout main
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Uncommitted changes prevent checkout
|
|
|
|
Stash your changes:
|
|
|
|
```bash
|
|
git stash
|
|
git checkout other-branch
|
|
git stash pop
|
|
```
|
|
|
|
Or commit them:
|
|
|
|
```bash
|
|
git commit -am "WIP: work in progress"
|
|
git checkout other-branch
|
|
```
|
|
|
|
### Branch doesn't exist
|
|
|
|
Fetch from remote first:
|
|
|
|
```bash
|
|
git fetch
|
|
git checkout branch-name
|
|
```
|
|
|
|
## Best practices
|
|
|
|
- Commit or stash changes before switching branches
|
|
- Use `git switch` for branches (Git 2.23+)
|
|
- Use `git restore` for files (Git 2.23+)
|
|
- Be careful with `--force`, it discards changes
|
|
- Create feature branches from an updated main branch
|
|
|
|
## Related commands
|
|
|
|
- [git switch](/git/switch) - Modern branch switching
|
|
- [git restore](/git/restore) - Modern file restoration
|
|
- [git branch](/git/branch) - Manage branches
|
|
- [git merge](/git/merge) - Combine branches
|
|
- [git stash](/git/stash) - Save temporary changes
|