# Git Commands Cheat Sheet

## 1. List files and versions

### List tracked files in the **local** repo

```bash
# All tracked files (from the index / last commit)
git ls-files

# Only committed files in current branch (same as what's in HEAD)
git ls-tree -r HEAD --name-only
```

### See version history of a file

```bash
# Commits that touched a file
git log -- path/to/file

# Show diffs for each commit touching the file
git log -p -- path/to/file

# Show content of a file at a specific commit
git show <commit>:path/to/file
```

`<commit>` can be a SHA, `HEAD`, `HEAD~1`, a branch name, or a tag.

---

## 2. Add version number to files

Git doesn't auto-inject version numbers into files, but common patterns:

### A. Use tags for repo versions

```bash
# Create a version tag
git tag -a v1.2.0 -m "Release 1.2.0"

# Push tags to remote
git push origin v1.2.0
# or all tags:
git push origin --tags
```

You then treat `v1.2.0` as the version of the whole repo (and thus of the files in it).

### B. Put version in a file and commit it

Maintain a file like `VERSION` or in your code/config:

```bash
echo "1.2.0" > VERSION
git add VERSION
git commit -m "Bump version to 1.2.0"
```

You can automate this with a script that:
- updates `VERSION`
- commits it
- creates a matching tag.

---

## 3. Commit files to Git (local)

Standard sequence:

```bash
# Stage all changes
git add .

# Or stage specific files
git add path/to/file1 path/to/file2

# Commit with a message
git commit -m "Describe what changed"
```

To include version bump in the same commit:

```bash
echo "1.2.0" > VERSION
git add VERSION
git add .
git commit -m "Release 1.2.0"
```

---

## 4. Commit files to the **remote** repository

"Commit to remote" = push your local commits:

```bash
# Push current branch to its upstream (often origin/main or origin/master)
git push

# First time, set upstream explicitly
git push -u origin main
```

If your remote is named something other than `origin`, use that name instead.

---

## 5. See files in the **remote** repository

You don't browse remote files directly; you ask your local Git about the remote's refs and trees.

### List branches and tags on the remote

```bash
git ls-remote origin
# or just branches:
git ls-remote --heads origin
# or just tags:
git ls-remote --tags origin
```

### List files in a remote branch (without cloning everything again)

Fetch first (if you haven't recently):

```bash
git fetch origin
```

Then list files in a remote branch:

```bash
# Files in origin/main
git ls-tree -r origin/main --name-only

# Files in origin/master
git ls-tree -r origin/master --name-only
```

You can also inspect a file at a remote ref:

```bash
git show origin/main:path/to/file
```

---

## 6. See files in **local vs remote**

### Local current branch

```bash
git ls-tree -r HEAD --name-only
# or
git ls-files
```

### Remote branch (e.g., `origin/main`)

```bash
git ls-tree -r origin/main --name-only
```

### Compare which files differ between local and remote

```bash
# Show paths that differ between local main and origin/main
git diff --name-only main origin/main
```