# Git Setup – Getting Started, Glossary, Tutorial, and Tools (tasks.md)

This document ties together everything from the FAQs and scripts into a single “getting started” guide for your Git workflow.

---

## 1. Getting Started (Quick Path)

Goal: have a working Git setup where you can:

- Pull the current project from your server.
- Make changes.
- Commit, tag a new version, and push back.

### 1.1 Prerequisites

On your local machine (Mac or Linux):

- Git installed: `git --version`
- SSH client working to your server on port 2222:

  ```bash
  ssh -p 2222 intel145@209.182.212.74 'echo SSH_OK'
  ```

- Your SSH key configured (either default `~/.ssh/id_rsa` or specified in `~/.ssh/config`).

### 1.2 One‑time SSH config (recommended)

Create or edit `~/.ssh/config`:

```ssh
Host 209.182.212.74
    User intel145
    Port 2222
    IdentityFile /Users/rbutare/.ssh/id_rsa
    IdentitiesOnly yes
```

Test:

```bash
ssh 209.182.212.74 'echo SSH_OK'
```

### 1.3 Clone the repo

```bash
mkdir -p ~/projects
cd ~/projects

git clone ssh://intel145@209.182.212.74:2222/home/intel145/websites/gitrepo/git.git git
cd git
```

Verify:

```bash
git remote -v
git branch -a
cat VERSION
git describe --tags --always
```

You now have the current version of the project.

---

## 2. Glossary (Key Terms)

- **Bare repository**:  
  A Git repo with no working files, used as central storage.  
  Example: `/home/intel145/websites/gitrepo/git.git`.

- **Working copy**:  
  A normal Git repo with checked‑out files where you edit and test.  
  Example: `~/projects/git` or `/home/intel145/websites/apps/git`.

- **Remote**:  
  A named URL pointing to another repo (usually the bare repo).  
  Common names: `origin`, `git`.

- **Branch**:  
  A line of development. You mainly use `main`.

- **Tag**:  
  A named, fixed point in history, typically a release: `v1.0.0`, `v2.1.0`, `v3.0.0`.

- **VERSION file**:  
  A single file in the repo root that holds the current release version (e.g., `3.0.0`).

- **git-bump-version**:  
  Your script that updates `VERSION`, commits it, and creates a tag.

---

## 3. Tutorial / Training: Typical Workflows

### 3.1 Start working (pull latest)

From your working copy:

```bash
cd ~/projects/git
git fetch origin
git checkout main
git pull
```

Or use the helper:

```bash
./git-ssh-pull
```

### 3.2 Make changes and commit

```bash
# Edit files
vi README.md
# Test your changes

# Stage and commit
git add -A
git commit -m "Improve README"
```

You can repeat edit/commit as many times as needed.

### 3.3 Release a new version (e.g., v3.0.0)

When the work is ready for a release:

```bash
./git-bump-version 3.0.0
git push origin main
git push origin --tags
```

Now:

- `VERSION` is `3.0.0`.
- Tag `v3.0.0` exists.
- Remote has your new commits and tag.

### 3.4 Update server working copy (if you have one)

On the server:

```bash
cd /home/intel145/websites/apps/git
git checkout main
git pull origin main
git fetch --tags
```

---

## 4. Tools & Checks

These are small tasks/scripts to confirm your setup is correct.

### 4.1 Confirm SSH works

```bash
ssh -p 2222 intel145@209.182.212.74 'echo SSH_OK'
```

If this fails, fix SSH before using Git.

### 4.2 Confirm remote is configured

From your working copy:

```bash
git remote -v
```

You should see something like:

```text
origin    ssh://intel145@209.182.212.74:2222/home/intel145/websites/gitrepo/git.git (fetch)
origin    ssh://intel145@209.182.212.74:2222/home/intel145/websites/gitrepo/git.git (push)
```

If not, set it:

```bash
git remote add origin ssh://intel145@209.182.212.74:2222/home/intel145/websites/gitrepo/git.git
```

Or update:

```bash
git remote set-url origin ssh://intel145@209.182.212.74:2222/home/intel145/websites/gitrepo/git.git
```

### 4.3 Confirm repository and app folders

On the server:

```bash
# Bare repo (storage only)
ls -ld /home/intel145/websites/gitrepo/git.git
# Should show a directory with HEAD, config, objects/, refs/, etc.

# Working copy (where you deploy/run)
ls -ld /home/intel145/websites/apps/git
# Should show your project files (README.md, VERSION, etc.)
```

Rules:

- Never edit or run `git commit` inside `/home/intel145/websites/gitrepo/git.git`.
- Always work in `/home/intel145/websites/apps/git` or your local clone.

### 4.4 Confirm current version

From any working copy:

```bash
cat VERSION
git describe --tags --always
git log --oneline -3
```

These should be consistent with your last release tag.

---

## 5. Included Tools (Scripts)

All scripts assume they are run from inside a working copy.

- `git-list-local [repo_path]`  
  List tracked files in the current branch.

- `git-list-remote [remote] [branch] [repo_path]`  
  List files in a remote branch.

- `git-show-version <ref> <path> [repo_path]`  
  Show contents of a file at a given commit/tag.

- `git-commit-push "message" [repo_path]`  
  `git add .`, commit, and push in one step.

- `git-bump-version [version] [repo_path]`  
  Update `VERSION`, commit, and tag a release.

- `git-ssh-pull [branch]`  
  Fetch and fast‑forward `main` from your SSH remote (named `git`).

Place these in a directory on your `PATH` (e.g., `~/bin`) and `chmod +x` them.

---

## 6. Quick Reference Commands

```bash
# Pull latest
git fetch origin
git checkout main
git pull

# Or:
./git-ssh-pull

# Make changes
git add -A
git commit -m "Your message"

# Release
./git-bump-version 3.0.0
git push origin main
git push origin --tags

# Inspect versions
git log --decorate --oneline -- README.md
git show v2.0.0:README.md
git diff v2.0.0 v3.0.0 -- README.md
```

Use this document together with `faq1.md`–`faq4.md` as your complete Git workflow guide.