Hands-on Practice with Local Repositories

Python Full Stack Web Developer Course - Week 1: Tuesday

Mastering Local Git Repositories

Now that we understand the fundamental concepts of version control and basic Git commands, it's time to get our hands dirty with practical exercises. Working with local repositories is like learning to drive in an empty parking lot before venturing onto busy streets—it allows you to develop essential skills in a controlled environment before collaborating with others.

In this session, we'll focus on hands-on practice with local Git repositories. Through a series of guided exercises, you'll gain experience with repository creation, file tracking, staging and committing changes, viewing history, and navigating your project's timeline. By the end of this session, you'll be comfortable with the core Git workflow and ready to apply these skills to your own projects.

Remember, mastery comes through repetition and practice. Don't worry if you make mistakes—that's part of the learning process. Git is designed to track your changes, not judge them, and almost any mistake can be undone.

Prerequisites for This Session

Required Software

$ git --version

Should display something like: git version 2.39.1

If Git is not installed or you need to update it:

Configuration Setup

Before we begin the exercises, let's ensure your Git environment is properly configured:

$ git config --global user.name "Your Name" $ git config --global user.email "your.email@example.com"

These settings identify you as the author of your commits. If you're concerned about privacy, you can use a GitHub-provided no-reply email address for public repositories.

$ git config --global init.defaultBranch main

Sets the default branch name to "main" for new repositories

Optional but Recommended

$ git config --global core.editor "code --wait"

For Visual Studio Code (replace with your preferred editor command)

Exercise 1: Creating and Initializing a Local Repository

In this exercise, we'll create a simple Python project and initialize it as a Git repository.

Goals

Step-by-Step Instructions

  1. Create a new project directory:
    $ mkdir python_todo_app $ cd python_todo_app
  2. Initialize a Git repository:
    $ git init

    You should see: Initialized empty Git repository in [path]/python_todo_app/.git/

    This creates a hidden .git directory that will store all version history and metadata for your project. Think of it as planting the seed for your project's timeline.

  3. Verify repository creation:
    $ ls -la

    This should list all files, including the hidden .git directory

  4. Create a README file:
    $ echo "# Python Todo Application\n\nA simple command-line todo application written in Python." > README.md

    Every good project starts with documentation. This creates a basic README file with a brief description.

  5. Create a .gitignore file:
    $ echo "__pycache__/\n*.py[cod]\n*$py.class\n.env\nvenv/\n.idea/\n.vscode/" > .gitignore

    This tells Git which files to ignore. For Python projects, we typically ignore bytecode files, virtual environments, and IDE-specific files.

  6. Create the main Python file:
    $ touch todo.py

    Now open this file in your text editor and add the following code:

    #!/usr/bin/env python3 """ Simple Todo Application This application allows users to add, view, and complete todo items from the command line. """ def main(): todos = [] print("Welcome to the Todo App!") print("Enter 'help' to see available commands.") while True: command = input("\nEnter command: ").strip().lower() if command == 'quit' or command == 'exit': print("Goodbye!") break elif command == 'help': print_help() elif command == 'list': list_todos(todos) elif command.startswith('add '): add_todo(command[4:], todos) elif command.startswith('complete '): try: index = int(command[9:]) - 1 complete_todo(index, todos) except ValueError: print("Please provide a valid number.") else: print("Unknown command. Enter 'help' to see available commands.") def print_help(): """Display available commands.""" print("\nAvailable commands:") print(" list - Show all todo items") print(" add [text] - Add a new todo item") print(" complete [num] - Mark an item as completed") print(" help - Show this help message") print(" quit - Exit the application") def list_todos(todos): """Display all todo items with their status.""" if not todos: print("No todos yet! Add some using 'add [text]'") return print("\nTodo List:") for i, todo in enumerate(todos, 1): status = "✓" if todo["completed"] else " " print(f"{i}. [{status}] {todo['text']}") def add_todo(text, todos): """Add a new todo item.""" if not text: print("Cannot add an empty todo. Try 'add [text]'") return todos.append({"text": text, "completed": False}) print(f"Added: {text}") def complete_todo(index, todos): """Mark a todo item as completed.""" if index < 0 or index >= len(todos): print(f"No todo with number {index + 1}") return todos[index]["completed"] = True print(f"Completed: {todos[index]['text']}") if __name__ == "__main__": main()
  7. Check status to see untracked files:
    $ git status

    This shows the current state of your working directory. You should see that README.md, .gitignore, and todo.py are listed as untracked files.

  8. Stage files for commit:
    $ git add README.md .gitignore todo.py

    This adds the files to the staging area, preparing them for commit.

  9. Verify staged files:
    $ git status

    Now you should see the files listed under "Changes to be committed".

  10. Create your first commit:
    $ git commit -m "Initial commit: Basic Todo application structure"

    This creates a snapshot of your project at this point in time with a descriptive message.

  11. Verify your commit:
    $ git log

    This shows your commit history. You should see your initial commit with the message you provided.

Understanding What Happened

In this exercise, you've gone through the complete basic Git workflow:

  1. You created a new directory and initialized it as a Git repository
  2. You added project files (README.md, .gitignore, and todo.py)
  3. You staged these files using git add
  4. You committed the staged files with a descriptive message
  5. You verified your commit using git log

Congratulations! You've created your first Git repository and made your first commit. This is the foundation of Git's version control system.

Exercise 2: Making Changes and Viewing Differences

Now that we have a repository with an initial commit, let's practice making changes, viewing differences, and creating additional commits.

Goals

Step-by-Step Instructions

  1. Enhance the Todo application:

    Open todo.py in your text editor and add a new function to save todos to a file:

    import json import os def save_todos(todos): """Save todos to a file.""" with open("todos.json", "w") as f: json.dump(todos, f) print("Todos saved to file.") def load_todos(): """Load todos from a file if it exists.""" if os.path.exists("todos.json"): with open("todos.json", "r") as f: return json.load(f) return []

    Now modify the main() function to use these new functions:

    def main(): todos = load_todos() print("Welcome to the Todo App!") print("Enter 'help' to see available commands.") while True: command = input("\nEnter command: ").strip().lower() if command == 'quit' or command == 'exit': save_todos(todos) print("Goodbye!") break elif command == 'help': print_help() elif command == 'list': list_todos(todos) elif command.startswith('add '): add_todo(command[4:], todos) elif command.startswith('complete '): try: index = int(command[9:]) - 1 complete_todo(index, todos) except ValueError: print("Please provide a valid number.") elif command == 'save': save_todos(todos) else: print("Unknown command. Enter 'help' to see available commands.")

    Also update the print_help() function to include the new 'save' command:

    def print_help(): """Display available commands.""" print("\nAvailable commands:") print(" list - Show all todo items") print(" add [text] - Add a new todo item") print(" complete [num] - Mark an item as completed") print(" save - Save todos to file") print(" help - Show this help message") print(" quit - Exit the application (auto-saves)")
  2. View changes with git diff:
    $ git diff

    This shows the differences between your working directory and the last commit. Lines prefixed with + are additions, and lines with - are removals.

  3. Stage the changes:
    $ git add todo.py
  4. View staged changes:
    $ git diff --staged

    This shows changes that are staged for commit. It's a good practice to review these before committing.

  5. Commit the changes:
    $ git commit -m "Add file persistence to save and load todos"
  6. Update the README file:

    Open README.md and enhance the documentation:

    # Python Todo Application A simple command-line todo application written in Python. ## Features - Add and list todo items - Mark items as completed - Persistent storage with JSON - Simple command-line interface ## Usage Run the application with: ``` python todo.py ``` ## Commands - `list` - Show all todo items - `add [text]` - Add a new todo item - `complete [num]` - Mark an item as completed - `save` - Save todos to file - `help` - Show help message - `quit` - Exit application (auto-saves)
  7. Check status again:
    $ git status

    This shows that README.md has been modified but not yet staged.

  8. Stage and commit the README changes:
    $ git add README.md $ git commit -m "Update README with features and usage instructions"
  9. View commit history:
    $ git log

    You should now see three commits in your history.

  10. Try a more compact log format:
    $ git log --oneline

    This shows a condensed version of the commit history, with one commit per line.

  11. View detailed changes in a specific commit:
    $ git show [commit_hash]

    Replace [commit_hash] with the hash of your second commit (the one adding file persistence). This shows the exact changes made in that commit.

Understanding What Happened

In this exercise, you've practiced:

These skills are essential for maintaining a clean and informative project history.

Exercise 3: Undoing Changes and Exploring History

In this exercise, we'll practice various ways to undo changes and explore your repository's history. Understanding how to revert mistakes is crucial for confident use of Git.

Goals

Step-by-Step Instructions

  1. Make a change you'll discard:

    Open todo.py and add a deliberately "bad" function that we'll discard later:

    def experimental_feature(): """A function we'll discard later.""" print("This is an experimental feature that isn't ready yet!") print("It might crash your system or delete all your todos!") return "Oops, something went wrong!"
  2. Check status and view changes:
    $ git status $ git diff
  3. Discard the unstaged changes:
    $ git restore todo.py

    This reverts todo.py to the version in the last commit, discarding your experimental function.

  4. Verify the changes were discarded:
    $ git status $ git diff

    You should see "nothing to commit, working tree clean" and no output from git diff.

  5. Make a change and stage it, then unstage it:

    Add a comment to todo.py:

    # TODO: Add support for due dates and priorities

    Stage the change:

    $ git add todo.py

    Now unstage it without discarding the change:

    $ git restore --staged todo.py
  6. Verify that the change is unstaged but still present:
    $ git status $ git diff

    You should see the file listed as modified but not staged, and git diff should show your comment.

  7. Stage and commit this change:
    $ git add todo.py $ git commit -m "Add comment for future enhancements"
  8. Examine your project at a previous commit:
    $ git log --oneline

    Find the hash of your initial commit.

    $ git checkout [initial_commit_hash]

    This puts you in a "detached HEAD" state, where you can look at your project as it was at the time of that commit.

  9. Notice the state of your files:

    Open todo.py in your editor and notice that it's reverted to its initial state without the file persistence functions.

  10. Return to the latest commit:
    $ git checkout main
  11. View changes between specific commits:
    $ git log --oneline $ git diff [initial_commit_hash] [second_commit_hash]

    This shows changes between your initial commit and the second commit.

  12. View changes to a specific file over time:
    $ git log --follow --oneline todo.py

    This shows only commits that affected todo.py.

  13. Recover a specific version of a file:

    Let's say we want to revert README.md to its original version without affecting other files.

    $ git checkout [initial_commit_hash] -- README.md

    This extracts README.md from the initial commit and places it in your working directory.

  14. Stage and commit this restored version:
    $ git add README.md $ git commit -m "Revert README to original version"

Understanding What Happened

In this exercise, you've practiced several important undoing operations:

These operations give you fine-grained control over your repository and allow you to recover from various types of mistakes.

Exercise 4: Working with Branches

In this exercise, we'll practice creating and managing branches in your local repository. Branches allow you to work on different features or experiments in isolation.

Goals

Step-by-Step Instructions

  1. Check your current branch:
    $ git branch

    This shows all local branches with an asterisk next to the current one (should be main).

  2. Create and switch to a new branch:
    $ git checkout -b feature/due-dates

    This creates a new branch called "feature/due-dates" and switches to it.

  3. Make changes in this branch:

    Let's modify todo.py to add support for due dates:

    # Add these imports at the top from datetime import datetime, timedelta # Modify the add_todo function def add_todo(text, todos): """Add a new todo item.""" if not text: print("Cannot add an empty todo. Try 'add [text]'") return # Check for due date in format: "text @tomorrow" or "text @YYYY-MM-DD" parts = text.split(" @") todo_text = parts[0] due_date = None if len(parts) > 1: date_text = parts[1].lower() try: if date_text == "today": due_date = datetime.now().strftime("%Y-%m-%d") elif date_text == "tomorrow": due_date = (datetime.now() + timedelta(days=1)).strftime("%Y-%m-%d") elif date_text == "nextweek": due_date = (datetime.now() + timedelta(days=7)).strftime("%Y-%m-%d") else: # Assume it's in YYYY-MM-DD format datetime.strptime(date_text, "%Y-%m-%d") # Validate date format due_date = date_text except ValueError: print(f"Warning: Invalid date format '{date_text}'. Date will not be set.") todos.append({"text": todo_text, "completed": False, "due_date": due_date}) print(f"Added: {todo_text}" + (f" (due: {due_date})" if due_date else "")) # Modify the list_todos function def list_todos(todos): """Display all todo items with their status.""" if not todos: print("No todos yet! Add some using 'add [text]'") return print("\nTodo List:") for i, todo in enumerate(todos, 1): status = "✓" if todo["completed"] else " " due_info = f" (due: {todo['due_date']})" if todo.get("due_date") else "" print(f"{i}. [{status}] {todo['text']}{due_info}") # Update the print_help function def print_help(): """Display available commands.""" print("\nAvailable commands:") print(" list - Show all todo items") print(" add [text] - Add a new todo item") print(" add [text] @YYYY-MM-DD - Add todo with due date") print(" add [text] @today/@tomorrow/@nextweek - Add with relative due date") print(" complete [num] - Mark an item as completed") print(" save - Save todos to file") print(" help - Show this help message") print(" quit - Exit the application (auto-saves)")
  4. Stage and commit these changes:
    $ git add todo.py $ git commit -m "Add support for due dates in todos"
  5. Switch back to the main branch:
    $ git checkout main

    Notice that todo.py reverts to its previous state without due date support.

  6. Create another branch for a different feature:
    $ git checkout -b feature/priority-levels
  7. Make changes for priority levels:

    Modify todo.py to add support for priorities:

    # Modify the add_todo function def add_todo(text, todos): """Add a new todo item.""" if not text: print("Cannot add an empty todo. Try 'add [text]'") return # Check for priority in format: "text !high" or "text !low" parts = text.split(" !") todo_text = parts[0] priority = "normal" # Default priority if len(parts) > 1: priority_text = parts[1].lower() if priority_text in ["high", "medium", "low"]: priority = priority_text else: print(f"Warning: Invalid priority '{priority_text}'. Using 'normal'.") todos.append({"text": todo_text, "completed": False, "priority": priority}) print(f"Added: {todo_text} (priority: {priority})") # Modify the list_todos function def list_todos(todos): """Display all todo items with their status.""" if not todos: print("No todos yet! Add some using 'add [text]'") return print("\nTodo List:") for i, todo in enumerate(todos, 1): status = "✓" if todo["completed"] else " " priority = todo.get("priority", "normal") priority_marker = "" if priority == "high": priority_marker = " [!]" elif priority == "low": priority_marker = " [.]" print(f"{i}. [{status}] {todo['text']}{priority_marker}") # Update the print_help function def print_help(): """Display available commands.""" print("\nAvailable commands:") print(" list - Show all todo items") print(" add [text] - Add a new todo item") print(" add [text] !high/!medium/!low - Add with priority") print(" complete [num] - Mark an item as completed") print(" save - Save todos to file") print(" help - Show this help message") print(" quit - Exit the application (auto-saves)")
  8. Stage and commit these changes:
    $ git add todo.py $ git commit -m "Add support for priority levels in todos"
  9. Switch back to main:
    $ git checkout main
  10. Merge the due dates feature:
    $ git merge feature/due-dates

    This incorporates the changes from the due-dates branch into main.

  11. Now merge the priority levels feature:
    $ git merge feature/priority-levels

    This will likely create a merge conflict since both branches modified the same parts of todo.py.

  12. Resolve the merge conflict:

    Open todo.py in your editor. You'll see sections marked with conflict markers:

    <<<<<<< HEAD # Due dates code from feature/due-dates branch ======= # Priority levels code from feature/priority-levels branch >>>>>>> feature/priority-levels

    Edit the file to integrate both features. For example:

    # Add these imports at the top from datetime import datetime, timedelta # Combined add_todo function def add_todo(text, todos): """Add a new todo item.""" if not text: print("Cannot add an empty todo. Try 'add [text]'") return # Extract priority if present parts = text.split(" !") todo_text = parts[0] priority = "normal" # Default priority if len(parts) > 1: priority_text = parts[1].lower() if priority_text in ["high", "medium", "low"]: priority = priority_text else: print(f"Warning: Invalid priority '{priority_text}'. Using 'normal'.") # Extract due date if present date_parts = todo_text.split(" @") todo_text = date_parts[0] due_date = None if len(date_parts) > 1: date_text = date_parts[1].lower() try: if date_text == "today": due_date = datetime.now().strftime("%Y-%m-%d") elif date_text == "tomorrow": due_date = (datetime.now() + timedelta(days=1)).strftime("%Y-%m-%d") elif date_text == "nextweek": due_date = (datetime.now() + timedelta(days=7)).strftime("%Y-%m-%d") else: # Assume it's in YYYY-MM-DD format datetime.strptime(date_text, "%Y-%m-%d") # Validate date format due_date = date_text except ValueError: print(f"Warning: Invalid date format '{date_text}'. Date will not be set.") todos.append({ "text": todo_text, "completed": False, "priority": priority, "due_date": due_date }) status_msg = f"Added: {todo_text}" if priority != "normal": status_msg += f" (priority: {priority})" if due_date: status_msg += f" (due: {due_date})" print(status_msg) # Combined list_todos function def list_todos(todos): """Display all todo items with their status.""" if not todos: print("No todos yet! Add some using 'add [text]'") return print("\nTodo List:") for i, todo in enumerate(todos, 1): status = "✓" if todo["completed"] else " " priority = todo.get("priority", "normal") priority_marker = "" if priority == "high": priority_marker = " [!]" elif priority == "low": priority_marker = " [.]" due_info = f" (due: {todo['due_date']})" if todo.get("due_date") else "" print(f"{i}. [{status}] {todo['text']}{priority_marker}{due_info}") # Updated print_help function def print_help(): """Display available commands.""" print("\nAvailable commands:") print(" list - Show all todo items") print(" add [text] - Add a new todo item") print(" add [text] @YYYY-MM-DD - Add todo with due date") print(" add [text] @today/@tomorrow/@nextweek - Add with relative due date") print(" add [text] !high/!medium/!low - Add with priority") print(" complete [num] - Mark an item as completed") print(" save - Save todos to file") print(" help - Show this help message") print(" quit - Exit the application (auto-saves)")
  13. Mark the conflict as resolved:
    $ git add todo.py $ git commit -m "Merge priority-levels feature and integrate with due-dates"
  14. View the branch history:
    $ git log --graph --oneline --all

    This shows a graphical representation of your branch history, including the merge.

  15. Clean up by deleting the merged branches:
    $ git branch -d feature/due-dates $ git branch -d feature/priority-levels

Understanding What Happened

In this exercise, you've practiced:

Branching is one of Git's most powerful features, allowing parallel development and experimentation without affecting your main codebase.

Exercise 5: Working with Git Aliases and Configuration

In this exercise, we'll customize Git to make it more efficient for your workflow by setting up aliases and configuration options.

Goals

Step-by-Step Instructions

  1. View your current Git configuration:
    $ git config --list

    This shows all your Git configuration settings.

  2. Create aliases for common commands:
    $ git config --global alias.st status $ git config --global alias.co checkout $ git config --global alias.br branch $ git config --global alias.ci commit $ git config --global alias.unstage "restore --staged" $ git config --global alias.last "log -1 HEAD" $ git config --global alias.lg "log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"
  3. Try out your new aliases:
    $ git st

    Equivalent to git status

    $ git lg

    Shows a colorized, compact log with branch graph

  4. Configure useful Git settings:
    $ git config --global core.editor "code --wait"

    Sets Visual Studio Code as your default editor for commit messages

    $ git config --global pull.rebase true

    Configures git pull to use rebase instead of merge

    $ git config --global push.default simple

    Push only the current branch to the upstream branch

    $ git config --global color.ui auto

    Enables automatic color in Git output

  5. Create a .gitignore file for Python projects:

    Create a global .gitignore file for all your Python projects:

    $ git config --global core.excludesfile ~/.gitignore_global

    Now edit this file (or create it if it doesn't exist):

    $ touch ~/.gitignore_global $ code ~/.gitignore_global

    Add common Python-specific entries:

    # Python __pycache__/ *.py[cod] *$py.class *.so .Python build/ develop-eggs/ dist/ downloads/ eggs/ .eggs/ lib/ lib64/ parts/ sdist/ var/ wheels/ *.egg-info/ .installed.cfg *.egg # Virtual Environments env/ venv/ ENV/ env.bak/ venv.bak/ # IDEs and editors .idea/ .vscode/ *.swp *.swo .DS_Store
  6. Create a Git hook for commit message validation:

    In your python_todo_app repository, create a commit-msg hook:

    $ mkdir -p .git/hooks $ touch .git/hooks/commit-msg $ chmod +x .git/hooks/commit-msg

    Edit the commit-msg file:

    $ code .git/hooks/commit-msg

    Add this script to enforce conventional commit message format:

    #!/bin/sh commit_msg_file=$1 commit_msg=$(cat "$commit_msg_file") # Check if the message follows the pattern: type: description if ! echo "$commit_msg" | grep -qE '^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .+$'; then echo "ERROR: Commit message does not follow the conventional format." echo "Please use one of the following types: feat, fix, docs, style, refactor, test, chore" echo "Example: feat: add user authentication" exit 1 fi # Check if the message is too short if [ $ { #commit_msg} -lt 10 ]; then echo "ERROR: Commit message is too short (less than 10 characters)" exit 1 fi # Check if the first letter of the description is capitalized if ! echo "$commit_msg" | grep -qE '^[^:]+: [A-Z]'; then echo "ERROR: Description should start with a capital letter" exit 1 fi exit 0
  7. Try out the commit hook:

    Make a small change to README.md and try committing with different message formats:

    $ echo "# Additional note" >> README.md $ git add README.md $ git commit -m "updated readme"

    This should fail because it doesn't follow the conventional format

    $ git commit -m "docs: Update README with additional note"

    This should succeed

Understanding What Happened

In this exercise, you've learned how to:

These customizations make Git more efficient and help maintain consistency across your projects.

Best Practices for Working with Local Repositories

Repository Organization

Commit Practices

Branching Strategy

History Management

General Tips

Common Git Pitfalls and How to Avoid Them

Committing Sensitive Information

Problem: Accidentally committing passwords, API keys, or other sensitive data.

Solution:

Committing Large Files

Problem: Adding large binary files bloats your repository and makes operations slow.

Solution:

Confusing the Working Directory, Staging Area, and Repository

Problem: Not understanding where your changes reside leads to confusion about what will be committed.

Solution:

Losing Work by Checkout or Reset

Problem: Using git checkout or git reset --hard without understanding their implications.

Solution:

Creating Messy Commit History

Problem: Making too many small, meaningless commits or combining unrelated changes into a single commit.

Solution:

Merge Conflicts

Problem: Frightening merge conflicts that seem impossible to resolve.

Solution:

Beyond the Basics: Next Steps with Git

As you become comfortable with local Git repositories, consider exploring these more advanced topics:

Remote Repositories and Collaboration

Advanced Git Operations

Git Internals

Git Tools and Integrations

Key Takeaways

By mastering local repositories, you've built a solid foundation for version control. As you continue your development journey, you'll find that Git becomes an invaluable tool for tracking your progress, exploring alternatives, and collaborating with others.

Assignment: Todo Application with Version Control

Extend the Todo application we've been working on by adding new features while practicing good Git workflow habits.

Requirements

  1. Continue working with the python_todo_app repository we created in the exercises
  2. Create a new branch for each of the following features:
    • feature/categories: Add the ability to categorize todos (work, personal, shopping, etc.)
    • feature/search: Add functionality to search todos by text
    • feature/recurring: Add support for recurring todos (daily, weekly, monthly)
  3. Implement each feature on its respective branch, making multiple meaningful commits for each
  4. Merge each feature branch back into main when complete
  5. Use appropriate commit messages following conventional commit format
  6. Resolve any merge conflicts that arise
  7. Document your Git workflow as you go, taking screenshots of important steps

Submission

Submit the following:

  1. A link to your GitHub repository (if you've pushed it) or a zip file of your local repository
  2. A document with screenshots showing your Git workflow, including:
    • Branch creation and switching
    • Commit history on each branch
    • Merge operations
    • Conflict resolution (if applicable)
  3. A brief reflection on what you learned about Git workflow and any challenges you encountered

Bonus Challenges

Additional Resources

Documentation and Books

Cheat Sheets and Quick References

Practice and Tutorials