first Create a new repo on GitHub manually

locally: use:
- git init

to initialize git in your local project

the name of the local branch is master while in GitHub the name is main so you have
to change
your local branch name or when you push there will be both master and main in
GitHub with master having your project and main being empty (while being the main
branch). change the name using:
- git branch -m main
then locally add all the files to commit them locally:
- git add .
- git commit -m "First commit"

Now your local git is updated. to upload it to git hub use

- git remote add origin https://github.com/Muhammad-FRAX/FiberOpticGIS.git

- git branch -M main
- git push -u origin main

Now it is uploaded. now lets talk about git status.

if you just used it without using "git fetch origin" before it, it will tell you if
your local git is updated (backed) or not compared to the actual project you have
locally, but if you used "git fetch origin" before it , it will tell you if it is
updated compared to the project on GitHub whether it is ahead of it and the GitHub
project needs updating.

✅ What git pull does:

It fetches the latest data from GitHub ✅
- git pull origin main

Then it merges it into your current local branch 🔁

So your local files will now be updated with whatever changes were on GitHub.

Command Behavior
git pull origin main Always pulls from origin/main.
git pull Pulls from the branch your local branch is tracking.

Below is a step-by-step, practical workflow for day-to-day use of GitHub in your

development process. This workflow assumes you have a local Git repository
connected to GitHub and covers common tasks such as pulling updates, creating
feature branches, committing changes, and merging your work back into the main
branch.

---

## **1. Daily Preparation**

**a. Start by syncing your local repo with GitHub:**

Before beginning any work, make sure your local branch is up to date.

```sh
git checkout main # Switch to your main branch
git pull origin main # Fetch and merge changes from GitHub
```

**b. Review open issues or tasks:**

Decide what feature or bug you will work on today. Using an issue tracker or
project board helps keep you organized.

---

## **2. Creating a Feature Branch**

Working in a dedicated branch keeps your main branch stable and allows for isolated
development.

1. **Create a New Branch:**

Replace `feature-name` with a short, descriptive name.
```sh
git checkout -b feature/feature-name
```

2. **Confirm You're on the New Branch:**

```sh
git branch
```
You should see an asterisk (*) next to your new branch name.

---

## **3. Coding and Local Development**

**a. Write Code & Test Locally:**

Develop your feature or fix locally. Use your preferred development tools and test
your changes thoroughly.

**b. Frequently Stage & Commit Changes:**

Keep your commits small and descriptive. This not only makes it easier to review
your work later but also helps in identifying issues.

```sh
git add . # Stage all changes (or list specific
files)
git commit -m "Implement [feature-name]: brief description"
```

---

## **4. Pushing Changes to GitHub**

Once you’re happy with your local commits, push your branch to GitHub for backup
and collaboration.

```sh
git push -u origin feature/feature-name
```

- The `-u` flag sets the upstream branch, so future pushes can be done with just
`git push`.

---
## **5. Creating a Pull Request (PR)**

**a. Open a PR on GitHub:**

- Navigate to your repository on GitHub.
- You should see a prompt to create a PR for your recently pushed branch.
- Provide a descriptive title and details about what you’ve implemented.

**b. Request Code Review:**

- Ask teammates to review your code.
- Address any feedback and update your branch as needed by committing more changes
and pushing them to the same branch.

---

## **6. Merging Your Work**

**a. Once Approved, Merge the PR:**

- Merge your PR using GitHub’s interface (Squash and merge is popular for keeping a
clean history).
- Alternatively, if working solo, you can merge locally and push:

```sh
git checkout main
git pull origin main # Make sure your local main is up to date
git merge feature/feature-name # Merge your feature branch into main
git push origin main
```

**b. Clean Up Feature Branches:**

After merging, delete your feature branch locally and on GitHub if no longer
needed.

```sh
git branch -d feature/feature-name # Delete locally
git push origin --delete feature/feature-name # Delete on GitHub
```

---

## **7. Ongoing Updates and Maintenance**

- **For New Work:**

- Always start by pulling the latest changes on your main branch.
- Create a new feature branch for each distinct piece of work.
- **Regular Commits:**
- Commit often to capture incremental progress.
- **Frequent Pushes:**
- Push your branches regularly to back up your work and share progress.
- **Merge Conflicts:**
- If you encounter conflicts during a pull, resolve them locally before pushing.
- **Use Descriptive Commit Messages:**
- This makes tracking changes easier for both you and your teammates.

---

## **8. Summary Workflow Recap**

1. **Sync:**
 ```sh
git checkout main
git pull origin main
```
2. **Branch:**
```sh
git checkout -b feature/feature-name
```
3. **Develop:**
- Code, test, and then:
```sh
git add .
git commit -m "Implement feature: description"
```
4. **Push:**
```
git push -u origin feature/feature-name
```
5. **Pull Request:**
- Open and merge via GitHub after reviews.
6. **Merge Locally (if needed):**
```sh
git checkout main
git pull origin main
git merge feature/feature-name
git push origin main
```
7. **Clean Up:**
```sh
git branch -d feature/feature-name
git push origin --delete feature/feature-name
```

Following this structured workflow helps maintain a clean project history,

facilitates code reviews, and ensures your repository stays up to date and
conflict-free.

this is a one time solution for the master/main problem:

git config --global init.defaultBranch main

it changes the default name to main for git so it matches GitHub

this renames your current branch to main: git branch -M main

- as practice i added a file README.md to GitHub manually and when i used git
status locally it told me it is UpToDate although there is a new file in the repo.

you expected it to say something like "you are behind by 1 commit" or "there are
changes to pull", right?

🤔 So why didn’t it show the README?

Because you likely haven’t fetched or pulled the remote changes yet.

**Git doesn't automatically check for remote changes every time you run git
status***

📥 git fetch
- Downloads new data (commits, branches, etc.) from the remote.
- Does NOT update your working files or merge anything.
- Keeps the changes stored in your local .git folder so you can review or merge
them later.
Think of it like checking for mail—you’ve brought it in, but you haven’t opened it
yet.
after it you use: git merge origin/main
🔄 git pull
- Runs git fetch plus git merge.
- Downloads the data and tries to integrate it directly into your current branch.
- If there are conflicting changes, you might get merge conflicts to resolve.
So git fetch is safer and more deliberate, while git pull is quicker but more
disruptive if you're not ready for incoming changes.

What Professionals Typically Do

✅ Create a Branch Per Feature or Fix
- Most teams follow a “one branch per unit of work” approach — whether it's a bug
fix, new feature, or even refactoring.
- This keeps changes isolated and manageable.
- Helps with code review, testing, rollback, and cleaner Git history.
Example:
git checkout -b feature/user-authentication
git checkout -b fix/login-button

*******************************************
Common Branching Standards in Teams
| Branch Type | Naming Convention | Purpose |
| main (or master) | Stable code | Production-ready or deployable code |
| dev or develop | Development integration | Aggregates features before merging to
main |
| feature/... | New features | e.g. feature/search-api |
| bugfix/... or fix/... | Bug fixes | e.g. fix/token-expiry |
| hotfix/... | Emergency prod fixes | e.g. hotfix/security-patch |
| chore/... | Non-code work | Docs, tooling, CI configs |

*****************************************************************
✅ Local Merge vs Remote Merge
- git checkout main followed by git merge feature/user-authentication only affects
your local repository.
- It brings the feature branch's changes into your local main.
- The feature branch still exists locally unless you delete it.
- So yes, your understanding is correct: that command merges the additions locally.

🌍 What Happens Remotely on GitHub

- If someone merged the feature into GitHub's main via a pull request, your local
main doesn’t know about it yet.
- You would need to run:
git checkout main
git pull origin main

- to update your local main with the latest changes from GitHub’s main.
So yes — your second option is spot on too. If you know the feature is already
merged on GitHub, you can simply pull the changes down instead of merging locally.🔥
Quick Recap| Action

| git merge feature/...

| Local only
 | Merges that branch into your current branch locally
|
| git pull origin main
| From GitHub
| Updates your local branch with remote changes
|
| Remote Pull Request (GitHub merge)
| Remote only
| Changes reflected on GitHub’s main, not locally yet

Typical Workflow After Feature Is Merged

✅ On GitHub (Remote)
- Once a pull request is merged, GitHub usually gives you a button to “Delete
branch.”
- This deletes the remote copy, but your local version still exists unless you
remove it.
Locally
To delete the local branch:
git branch -d feature/my-task # If already merged
git branch -D feature/my-task # Force delete (even if not merged)

To delete the remote version:

git push origin --delete feature/my-task