Unit 5: Version Control

I. Orientation — The Principle of Version Control

Version control is a system for recording changes to files over time so that users can review history, compare versions, coordinate work, and restore earlier states. Git (created by Linus Torvalds in 2005) is a distributed version control system: every complete local repository contains both the project files and their recorded history.

• Version: A recorded state of one or more project files at a particular point in development.
• Repository: A project directory whose changes and history are managed by a version control system.
• Distributed model: Each developer can hold a complete repository, rather than depending entirely on one central server.
• Working directory: The visible project files that a user edits.
• Staging area: Git’s intermediate area for selecting the exact changes that will enter the next commit.
• Commit: A saved snapshot of staged changes, identified by a unique hash such as a31f9c2.
• Branch: An independent line of development represented by a movable pointer to a commit.
• Remote repository: A repository stored on another computer or hosting service, such as GitHub.
• Core workflow: Work normally moves from the working directory to the staging area, then into repository history:

Edit files → Stage changes → Commit changes → Push to a remote

• Important convention: Git commands are normally entered in a terminal while the current directory is the relevant project directory.

II. Git and GitHub — Local Version Control and Online Collaboration

A. Overview of Git and GitHub

Git manages project versions, while GitHub provides online hosting and collaboration services for Git repositories.

1. Git

   • Nature: Git is software installed on a computer and commonly used through commands such as git add and git commit.
   • Primary role: It records snapshots, creates branches, compares changes, and restores earlier versions.
   • Local operation: Commands such as git status, git log, and git branch can work without an internet connection.
   • Tracked content: Git is best suited to text-based files, including .py, .html, .md, and source-code files.
   • Metadata directory: Git stores repository information inside a hidden .git directory.

2. GitHub

   • Nature: GitHub is a web platform that hosts Git repositories; it is not Git itself.
   • Primary role: It supports remote backup, sharing, pull requests, issue tracking, code review, and team permissions.
   • Identification: A repository may have a web address such as https://github.com/username/project.git.
   • Public and private repositories: Public repositories are generally visible to everyone, while private repositories are limited to approved users.
   • Authentication: GitHub accepts secure methods such as browser-based authentication, personal access tokens, and SSH keys rather than account passwords for Git command-line operations.

B. Relationship Between Local and Remote Repositories

Local and remote repositories are separate copies whose histories are exchanged through explicit Git commands.

• Remote name: The default remote is conventionally called origin, although another name can be used.
• Push: git push sends local commits to a remote repository.
• Fetch: git fetch downloads remote history without automatically integrating it into the current branch.
• Pull: git pull normally fetches remote changes and then integrates them into the current branch.
• Clone: git clone URL downloads an existing remote repository and its history into a new local directory.
• Synchronization principle: Saving a file does not create a commit, and creating a commit does not automatically upload it to GitHub.

III. Initial Setup — Preparing Git and GitHub

A. install git and create a GitHub account

Installing Git provides the local version control tools, while a GitHub account provides an identity and workspace for hosted repositories.

• Windows installation: Download Git from the official Git website, run the installer, and retain suitable defaults unless a course specifies otherwise; Git Bash is included as a terminal.
• macOS installation: Git may be installed through Apple Command Line Tools or a package manager:

xcode-select --install

• Linux installation: Use the distribution’s package manager; for Debian or Ubuntu systems:

sudo apt update
sudo apt install git

• Installation check: Displaying a version confirms that the executable is available:

git --version

• User identity: Git places the configured name and email address in commit metadata:

git config --global user.name "Amina Yusuf"
git config --global user.email "amina@example.com"

• Configuration scope: --global applies the setting to the current user’s repositories; omitting it inside a repository creates a repository-specific setting.
• Configuration check: The following command lists settings and their sources:

git config --list --show-origin

• GitHub registration: Visit GitHub, choose a unique username, provide an accessible email address, create a strong password, and verify the email address.
• Account security: Enable two-factor authentication and store recovery codes securely; the GitHub username forms part of URLs such as github.com/username.
• Profile details: A display name, biography, avatar, and location may be added, but they do not replace the Git identity configured with git config.
• Privacy consideration: A commit email can become visible in repository history; GitHub can provide a private noreply email address for commits.

IV. Local Repository Workflow — Recording a Project’s History

A. create a local git repository

Creating a local repository initializes Git’s tracking structures inside a project directory.

• Project directory: Make a directory and enter it before initialization:

mkdir orientation-project
cd orientation-project
git init

• Initialization result: git init creates the hidden .git directory containing objects, references, configuration, and other repository data.
• Existing files: Initialization does not delete or immediately commit existing files; it only prepares the directory for Git tracking.
• Repository status: The following command reports the current branch, staged changes, modified files, and untracked files:

git status

• Default branch: The initial branch is often named main, although the configured or installed Git version may use another name.
• Explicit branch name: A new repository can be initialized with main where the installed Git version supports it:

git init -b main

• Location warning: Initializing the wrong directory may cause unrelated files to appear as untracked; verify the path with pwd on Unix-like terminals or cd on Windows.
• Removal effect: Deleting .git removes Git history and configuration from that local directory but ordinarily leaves the working files intact.

B. add a new file to the repository

Adding a file places its current contents in Git’s staging area for inclusion in a future commit.

• File creation: A plain-text project description can be created as README.md:

# Orientation Project

This project demonstrates a basic Git workflow.

• Untracked state: Before staging, git status identifies README.md as an untracked file because no committed snapshot contains it.
• Single-file staging: Add the specific file to the staging area:

git add README.md

• Verification: Running git status again lists the file under changes to be committed.
• Meaning of add: git add stages content; it does not permanently record the change and does not upload anything to GitHub.
• Multiple files: git add . stages eligible changes under the current directory, so git status should be reviewed first to avoid including temporary or sensitive files.
• Ignored files: A .gitignore file can name files Git should normally leave untracked:

.env
*.log
__pycache__/

• Restaging: If a staged file is edited again, its newly edited content must be staged with another git add before that content enters the next commit.
• Unstaging: git restore --staged README.md removes the file from the staging area while preserving it in the working directory.

C. Creating a commit

Creating a commit stores a permanent repository snapshot of the staged content together with identifying metadata.

• Commit command: A concise message describes the purpose of the saved change:

git commit -m "Add project README"

• Recorded metadata: A commit includes the author, email, date, message, project snapshot, parent commit, and unique hash.
• Snapshot principle: Git conceptually stores project states rather than merely saving a sequence of editing instructions.
• Selective recording: Only staged changes enter the commit; unstaged modifications remain in the working directory.
• History inspection: Display commits from newest to oldest:

git log --oneline

• Commit message quality: Use a specific command-style message such as Add login validation, rather than vague wording such as changes.
• Logical scope: One commit should represent one coherent unit of work, making the history easier to inspect and reverse.
• Clean-state check: After committing all current changes, git status reports that there is nothing to commit and the working tree is clean.
• Remote publication: A local commit remains local until it is pushed to a configured remote; committing and pushing are distinct actions.

V. Branching — Developing Along an Independent Line

A. Creation of a new Branch Profile.

A new branch creates an independent development line, while “branch profile” is not a formal Git object and usually refers to a descriptively named branch for profile-related work.

• Branch purpose: A branch allows work on a feature, fix, or experiment without immediately changing the main development branch.
• Branch creation and switch: Create a branch named feature/profile and move to it:

git switch -c feature/profile

• Equivalent older syntax: The following command performs the same common operation:

git checkout -b feature/profile

• Name structure: In feature/profile, feature identifies the category and profile identifies the task; the slash is a naming convention, not a directory.
• Branch listing: git branch lists local branches, with an asterisk marking the currently checked-out branch.
• Independent commits: Files edited and committed on feature/profile advance that branch while main continues to point to its earlier commit.
• Publishing the branch: Send it to GitHub and establish its upstream connection:

git push -u origin feature/profile

• Upstream effect: After -u records the tracking relationship, later updates can usually be sent with git push.
• Integration: Completed branch work may be merged locally or proposed through a GitHub pull request for discussion and review.
• Profile distinction: A GitHub user profile describes an account; it is different from a Git branch. Editing a profile does not create repository history unless profile-related files are stored and committed in a repository.
• Safe switching: Commit or appropriately preserve unfinished work before changing branches, especially when edits could conflict with files on the destination branch.