Starting Git Projects

A Complete Guide

Author

Chuck Nelson

Published

October 15, 2025

Git Project Startup

This document provides a comprehensive guide to initiating projects under Git version control, covering foundational concepts, key workflows, and best practices for both local and collaborative remote work.

1 What is Git Used For?

Git is a Distributed Version Control System (DVCS). Think of it as a powerful time machine for your code.

It is used for:

  • Tracking Changes: Recording every modification, deletion, or addition to your files over time, allowing you to view and revert to any previous state.

  • Collaboration: Enabling multiple developers to work on the same project simultaneously without stepping on each other’s toes.

  • Branching: Creating isolated environments (branches) to test new features or fix bugs without affecting the stable main version of the project.

  • Backup: Storing a secure, off-site copy of your entire project history.

2 Local vs. Remote Repositories

There are generally two places where your project’s history (the repository) can exist:

Feature Local Repository (.git folder on your computer) Remote Repository (e.g., GitHub, GitLab)
Location On your machine (developer’s hard drive). On a server accessible via the internet.
Primary Use Daily work, committing changes, creating feature branches. Collaboration, centralized backup, sharing code.
Access Only accessible to you. Accessible by authorized team members.
Commands git init, git commit, git merge git clone, git push, git pull

3 Local Repositories: Starting Points and Trade-offs

Starting with a local repository allows you to version control files immediately, which is ideal for exploration or proof-of-concept work.

Benefits

Starting with a local repository gives a developer the ability to version control early files while exploring proof-of-concept and alternative designs. This has several benefits such as:

  • Version Control Early: You can start tracking changes before committing to a remote platform, useful for sensitive or exploratory work.

  • Speed: Committing changes is instantaneous as it’s purely a local disk operation.

  • Offline Work: You can continue committing changes even without an internet connection.

  • Experimentation: Branching alternative designs, reverting to earlier stages, and merging different design decisions are easily done locally.

Shortcomings

Local repositories work for single developer projects as the repository exists only for the user that created it. However, there are also some shortcomings:

  • Difficulty Working from Multiple Locations: If you switch computers, your history isn’t automatically available.

  • Difficulty Collaboration: Multiple developers cannot easily work on the project simultaneously.

  • No Off-site Backup: If your local disk fails, the entire project history is lost.

  • No CI/CD: Remote-based features like Continuous Integration/Deployment are unavailable.

Starting a Local Repository: How-To

We’ll cover two scenarios: creating a blank project, and bringing an existing folder under Git control.

Scenario 1: New Blank Folder \(\to\) Local Repo \(\to\) Remote Push (Standard Start)

This is for starting a project completely from scratch.

  1. Create Project Directory:

    mkdir my-new-app
cd my-new-app

  2. Initialize Git Repository:

    git init

    (This creates the hidden .git folder)

  3. Add Initial Files and Commit:

    # Create best-practice starter files
touch README.md .gitignore
git add .
git commit -m "Initial blank project setup with essential files"

  4. Create Remote Repository (External Step):

    • Go to GitHub/GitLab/Bitbucket and create a new, empty repository (do not check the box to add a README or license, as you created them locally).

  5. Connect Local to Remote and Push:

    • Replace <REMOTE_URL> with the URL provided by your hosting service.
    git remote add origin <REMOTE_URL>
git branch -M main
git push -u origin main
    • Note: -u sets the remote origin as the upstream for your main branch, meaning future git push commands won’t require extra arguments.

Scenario 2: Existing Project \(\to\) Local Repo \(\to\) Remote Push (New Remote)

This is the process for bringing a folder full of existing files under Git control and pushing it to a brand-new, empty remote repository.

  1. Navigate to Existing Project Folder:

    cd my-existing-legacy-code

  2. Initialize Git Repository:

    git init

  3. Add and Commit All Existing Files:

    Before adding, ensure you have a proper .gitignore file (see Section 4.2).

    git add .
git commit -m "Initial commit of existing legacy project"

    (All files are now tracked in your local history.)

  4. Create Empty Remote Repository (External Step):

    • Go to your hosting platform (GitHub, GitLab, etc.).
    • Create a new repository and crucially, do not initialize it with a README, license, or .gitignore file. It must be completely empty.
    • Copy the remote URL (e.g., HTTPS or SSH).

  5. Connect Local to Remote and Initial Push:

    • Use git remote add origin to name the remote location, and then git push -u to send your local history and files up, creating the main branch on the remote server.
    # Replace <REMOTE_URL> with the copied URL
git remote add origin <REMOTE_URL>

# Push local main branch to create it on the remote
git push -u origin main

4 Project Setup Essentials (Best Practices)

Every professional Git project should start with these foundational elements to ensure consistency, usability, and clean version control.

The README.md File

The README.md (written in Markdown) is the welcome mat for your repository. It is the first file any visitor or new collaborator will see.

What to include:

  • Project Title and Description: A clear, concise summary of what the project does.
  • Installation Instructions: Step-by-step guide on how to get the project running locally (dependencies, setup commands, e.g., npm install).
  • Usage Examples: How to run the application or use the code library.
  • Contributing Guide (Optional): Details on how others can submit bug reports or pull requests.
  • License: Information about the project’s licensing.

The .gitignore File & Language Specifics

The .gitignore file tells Git which files or patterns to always ignore and prevent from being tracked or committed. This keeps your repository clean by excluding generated files, local dependencies, and secrets.

Common Entries by Project Type:

Project Type Common Files/Folders to Ignore Reasoning
Node.js / React / Storybook /node_modules, npm-debug.log*, .env, /dist, /build, storybook-static/ Dependency cache, build output (production), local secrets, and Storybook output.
Python __pycache__/, *.pyc, .venv/, .mypy_cache/, *.egg-info/ Caching bytecode, virtual environments, and build metadata.
Java /bin, *.class, *.jar, *.war, target/, .project, .settings/ Compiled output, distribution files, and IDE configuration files (especially Eclipse).
C++ / C *.o, *.exe, *.out, /build, *.gch, *.dSYM Object files, executables, build directories, debug symbols, and precompiled headers.
General .DS_Store, Thumbs.db, *.log, *.tmp Operating System/Editor junk and temporary files.

Best Practice: Use an online generator like gitignore.io to combine templates for your specific language and OS.

IDE Configuration (VSCode)

If your team uses Visual Studio Code (VSCode), you can share project-specific settings by including the .vscode/ directory. Crucially, this directory should be committed to Git.

Key Files in .vscode/:

File Name Purpose Git Status
settings.json Contains workspace-specific settings (e.g., formatter rules, indentation size, specific linting rules). Ensures code consistency across developers. Commit
extensions.json Contains recommended extensions for the project. VSCode suggests installing these to new collaborators. Commit
launch.json Defines debugging configurations (e.g., how to start the Node server or attach to the Python process). Commit
tasks.json Defines common build or run tasks accessible via the VSCode task menu. Commit

5 Setting Up Your Local Git Environment

Before you make your first commit or interact with any remote repository, you need to configure your local Git identity and set up a secure access method.

Configure Your Identity (Mandatory)

Git uses this information to tag all of your commits. Your university or employer may require a specific email address. These are set globally once per computer.

  1. Set Your User Name:

    git config --global user.name "Your Full Name"

  2. Set Your Email Address:

    git config --global user.email "your.email@example.com"

  3. Verify Configuration:

    git config --list | grep user
# Should output:
# user.name=Your Full Name
# user.email=your.email@example.com

Secure Access for Private Repositories

When you push or pull code from a private repository (on GitHub, GitLab, etc.), you must authenticate. Using a password is often disabled; instead, you should use SSH or a Personal Access Token (PAT).

Option B: Personal Access Token (PAT)

PATs are unique strings that grant access to your remote repositories via HTTPS. They are often used for security reasons, as they can be revoked instantly.

  • Setup:
    • Generate a PAT from your GitHub/GitLab settings, granting it the necessary permissions (usually repo).
    • Copy the generated token (it is shown only once!).
  • Usage: When cloning or pushing via the HTTPS URL (starts with https://), the system will prompt you for your username and then the PAT (instead of your normal password). It’s best practice to use a Git Credential Manager to store the PAT securely on your computer.

6 Remote Repositories: Starting Points and Trade-offs

Starting with a remote repository is the standard workflow for team projects.

Hosting Remote Repositories

Remote repositories are hosted on dedicated servers. The most popular platforms are:

  • GitHub: Widely used for open-source and professional work.

  • GitLab: Offers integrated CI/CD and DevOps features.

  • Bitbucket: Popular for private repositories and often integrated with Atlassian tools (Jira, Confluence).

Repositories can be Public (viewable by anyone) or Private (viewable only by invited collaborators).

Benefits

The benefits of a remote repository primarily revolve around collaboration and security:

  • Centralized Source of Truth: All team members pull from and push to the same, definitive repository.

  • Data Redundancy/Backup: The remote host provides a safe, offsite backup of your project.

  • Collaboration Tools: Platforms offer features like Issue Tracking, Code Review, and Pull Requests (essential for professional work).

  • CI/CD Integration: Services can automatically run tests or deploy code upon a successful push.

Shortcomings

While necessary for modern development, remote repositories introduce some constraints:

  • Internet Dependency: You must be online to clone, push, or pull changes.

  • Learning Curve: Concepts like push/pull conflicts, merging, and remote branch management add initial complexity for new users.

  • Authentication: Requires managing SSH keys or access tokens for secure interactions with the host.

  • Cost: While public and small private repositories are often free, large projects or specialized features may require paid subscriptions.

Starting a Remote Repository: How-To

Scenario 3: New Remote Repo \(\to\) Local Clone

This is the standard starting point when joining an existing project or using platform features (like adding a license/README) on creation.

  1. Create Remote Repository (External Step):

    • Go to GitHub/GitLab and create a new repository. This time, check the box to initialize it with a README, license, or .gitignore.

  2. Get the Repository URL:

    • Copy the HTTPS or SSH clone URL (based on your chosen authentication method in Section 5.2).

  3. Clone the Repository Locally:

    • The clone command automatically initializes the Git folder (git init), downloads all files, and sets up the remote tracking (git remote add origin).
    git clone <REMOTE_URL>

  4. Navigate into the Cloned Folder:

    cd <project-name>

  5. Make Changes, Commit, and Push:

    # Make a change, e.g., edit the README or create a new file
touch example.txt

# Add the new file to the staging area
git add example.txt

# Commit the changes locally
git commit -m "Added initial example file"

# Push the local commits to the remote repository
git push

7 Working on Open Source Projects

The standard workflow for contributing to open-source or external projects uses a process that keeps your changes separate until they are ready for review. This typically involves Forking and Pull Requests (PRs).

The Fork-Clone-PR Workflow

Step Action Command/Location Purpose
1. Fork Create a copy of the main repository. Platform UI (GitHub/GitLab) Puts the project under your personal account for development.
2. Clone Download your fork locally. `git clone <YOUR_FORK_URL>` Allows you to start development on your machine and maintain the original project history.
3. Push Changes Commit changes to a new branch on your fork. `git push -u origin <branch-name>` Isolates your work and keeps your local branch clean.
4. Pull Request (PR) Request that the original project maintainers review and merge your changes. Platform UI (GitHub/GitLab) Starts the code review process.

8 Branching Workflows and Strategies

Branching is how Git enables parallel development. You should never commit directly to the main branch. All work, whether a new feature or a bug fix, should be done in an isolated branch.

Essential Branching Commands

Command Purpose Example
git branch Lists all local branches in the current repository. git branch
git branch <name> Creates a new branch (but does not switch to it). git branch feature/checkout
git switch <name> Switches to an existing branch (modern command). git switch feature/checkout
git switch -c <name> Creates a new branch AND switches to it (shorthand). git switch -c feature/checkout
git merge <name> Merges the named branch’s changes into your current branch. git merge feature/checkout
git branch -d <name> Deletes the local branch (safe, only if merged). git branch -d feature/checkout

The Feature Branch Workflow (The Student Standard)

This is the simplest and most common strategy, ideal for students and small teams.

  1. Start on Main: Ensure your local main branch is up-to-date with the remote:

    git switch main 
git pull origin main

  2. Create a New Branch: Base your new feature work off of the clean main branch:

    git switch -c feature/add-user-login

  3. Work and Commit: Develop the feature, committing frequently to the branch.

    # (after editing files...)
git add .
git commit -m "feat: implement basic user authentication logic"

  4. Push to Remote: Push your branch to the remote repository for backup and collaboration:

    git push -u origin feature/add-user-login

  5. Merge (via Pull Request): When the feature is complete, merge it back into main. In professional settings, this is always done via a Pull Request (PR) on the hosting platform (GitHub/GitLab) to trigger automated tests and code review.

Branch Naming Conventions (Best Practice)

Using a standard convention makes it easy to understand a branch’s purpose at a glance.

Prefix Purpose Example
feature/ New functionality or user stories. feature/payment-integration
fix/ Fixing a bug in the production code. fix/mobile-menu-crash
refactor/ Changes to code structure without changing behavior. refactor/clean-up-api-utils
docs/ Updates only to documentation files. docs/update-install-guide

9 Self-Hosting Options for Remote Repositories (FOSS)

If you need full control over your code, data, and continuous integration pipelines, self-hosting is the best solution. The following are the most popular Free and Open-Source Software (FOSS) options.

Platform Best Use Case Key Features System Requirements
Gitea Small teams, hobbyists, personal use, resource-constrained hardware (e.g., Raspberry Pi). Extremely lightweight and fast (Go language), single binary deployment, includes basic features like issue tracking and simple CI/CD (Gitea Actions). Very low (can run on 256MB RAM).
GitLab (Community Edition) Large organizations, complex DevOps pipelines, professional projects requiring comprehensive features. All-in-one DevOps platform, includes robust CI/CD, container registry, security scanning, and complex project management tools natively. High (minimum 4GB to 8GB+ RAM recommended).
Gogs Minimalist personal server, simple repository hosting without advanced features. Designed for maximum simplicity and low resource usage, even more lightweight than Gitea, but has fewer features and less community activity. Minimal (less than Gitea).

Important Self-Hosting Considerations

  • Resources: If you are running on a virtual private server (VPS) or an older machine, Gitea or Gogs will be significantly easier to manage and maintain due to their low resource requirements.
  • Feature Set: If you need a fully integrated CI/CD pipeline (runners, detailed YAML configurations) or built-in security features for professional work, GitLab CE is often the better, albeit heavier, choice.
  • Maintenance: Self-hosting means you are responsible for installation, updates, security patching, and backups. Choose the option you are most comfortable maintaining.
Back to top