Starting a Project

This section describes the process of initializing a Git project. You typically obtain a Git repository in one of two ways: you can take a local directory that is currently not under version control, and turn it into a Git repository, or you can clone an existing Git repository from elsewhere.

In either case, you end up with a Git repository on your local machine, ready for work.

Initialize the Git Repository

Before initializing a Git repository, navigate to the directory of your existing project or create a new project folder. Open a terminal or command prompt and change into the project directory:

cd path/to/your/project

Initializing a Git repository involves setting up Git to manage your project's version control. It creates a hidden subfolder within your project that houses the internal data structure required for version control.

Version control allows you to track changes, collaborate with others, and revert to previous states of your project. Initializing a Git repository is the first step to harnessing these benefits.

Run the following command to initialize a Git repository in your project folder:

git init

After running git init, Git creates a .git directory in your project folder. This directory contains all the necessary files for version control.The .git directory is where Git stores information about your project's history, branches, configurations, and more.

git init Options

Initialize a New Git Repository

git init

Initializes a new Git repository in the current working directory.

Initialize in a Specific Directory

git init <directory>

Initializes a new Git repository in the specified directory.

Example:
```
git init my_project
```

git init Flags

--bare

The git init --bare command is used to create a new Git repository with a bare structure. A bare repository does not have a working directory like a typical Git repository. Instead, it only contains the version history, branches, tags, and configuration files. This type of repository is commonly used for remote repositories in a centralized workflow, where multiple developers collaborate on the same codebase.

To create a bare repository using git init --bare, you simply run the command in the desired location where you want to create the repository:

git init --bare <repository_name>

<repository_name>: The name of the bare repository directory to be created. This parameter is optional, and if not provided, Git will create the repository in the current directory.

Characteristics of a Bare Repository

No Working Directory: Unlike a regular Git repository, a bare repository does not have a working directory where you can edit files. It only contains the version history and other metadata.
Storage of Commits and Branches: The bare repository stores commits, branches, tags, and other version control information directly in its .git directory, without the need for a separate working directory.
Remote Access: Bare repositories are typically used as central repositories that multiple developers can push changes to and pull changes from. They are accessed over a network, often via protocols like SSH or HTTP.
Collaboration: Bare repositories facilitate collaboration by serving as a central point where developers can share their changes and synchronize their work.

Use Cases

Centralized Workflow: In a centralized workflow, a bare repository is set up on a server or a central location accessible to all team members. Developers push their changes to this repository, and other team members pull changes from it.
Remote Hosting Services Many remote hosting services, such as GitHub, GitLab, and Bitbucket, use bare repositories to store project code. When you create a new repository on one of these platforms, it is typically initialized as a bare repository on the server.

Advantages of Bare Repositories

Efficient Collaboration: Bare repositories simplify collaboration by providing a central location for sharing changes and synchronizing work among team members.
Reduced Disk Usage: Bare repositories consume less disk space compared to regular repositories since they do not store individual working copies of files.
Security: Since a bare repository does not have a working directory, it cannot accidentally expose sensitive information or execute malicious code.
It is not recommended to work directly with a bare repository on your local machine. Instead, clone the bare repository to create a working copy with a proper working directory where you can edit files and commit changes.

`--template=<tmplt_dir>`

git init --template=<template_directory>

Initializes a new Git repository using the specified template directory. This can be useful for setting up a custom project structure.

Example:

git init --template=/path/to/custom/template

The git init --template command is used to initialize a new Git repository with a custom template directory. This feature allows you to provide a set of predefined files and directories that will be automatically copied into the newly initialized repository. It can be useful for setting up a standardized project structure, including default configuration files, README templates, or other resources commonly used in your projects.

Let's say you have a template directory named my_template with the following structure:

my_template/
├── .gitignore
├── README.md
└── scripts/
    └── setup.sh

To initialize a new Git repository using this template, you would run the following command:

git init --template=my_template

After running this command, Git will create a new repository in the current directory, copying the files and directories from the my_template directory into the newly created repository. The resulting repository will have the same structure as the template directory, including the .gitignore file, README.md, and the scripts directory with its contents.

Use Cases:
Standardized Project Setup: You can use a template directory to define a standardized project structure, including default configuration files, license files, and directory layouts.
Consistent READMEs: By including a README template in the template directory, you can ensure that all new repositories start with a consistent README file that includes essential project information.
Custom Gitignore Files: Including a .gitignore file in the template directory allows you to specify default patterns for ignoring files and directories commonly found in your projects.
The --template option is available in Git version 1.7.1 and later.
You can customize the template directory to suit your specific needs, including any files or directories that you want to include in all new repositories.

Using git init --template allows you to streamline the process of setting up new Git repositories by providing a standardized starting point for your projects. It promotes consistency and helps ensure that all new repositories adhere to your project's conventions and best practices.

`--separate-git-dir=<git_dir>`

The git init --separate-git-dir=<git_dir> command is used to initialize a new Git repository while specifying a separate directory (<git_dir>) to store the Git metadata (.git directory). This allows you to decouple the location of the repository's working directory from the location of the .git directory, providing flexibility in managing your Git setup.

git init --separate-git-dir=<git_dir> [<working_dir>]

<git_dir>: The path to the directory where Git should store its metadata (.git directory).
<working_dir>: (Optional) The path to the directory where the working directory should be created. If not provided, the current directory is used.

Let's say you want to create a new Git repository with the working directory located in the ~/projects/my_project directory and the Git metadata stored in the ~/git/my_project.git directory. You would use the following command:

git init --separate-git-dir=~/git/my_project.git ~/projects/my_project

After running this command, Git will initialize the repository in the specified working directory (~/projects/my_project) and create the .git directory with all the necessary metadata in the separate location (~/git/my_project.git).

Decoupling Working Directory and Git Metadata: This command allows you to separate the working directory from the Git metadata, which can be useful in various scenarios, such as managing multiple working directories that share the same Git repository.
Centralized Git Metadata Storage: You can centralize the storage of Git metadata by specifying a shared location for the .git directory, which can be accessed by multiple working directories.
Custom Git Metadata Location: You may have specific requirements or constraints that necessitate storing the Git metadata in a custom location, such as a network drive or a designated system directory.
When using git init --separate-git-dir, the specified <git_dir> directory must not exist prior to running the command. Git will create the directory and initialize it as a new Git repository.
If <working_dir> is not provided, the current directory is used as the working directory.

Using git init --separate-git-dir=<git_dir> provides flexibility in managing your Git repositories by allowing you to customize the location of the Git metadata independently of the working directory. This can be beneficial in various workflows and setups, especially when dealing with multiple repositories or centralized storage of Git metadata.

`--quiet` or `-q`

git init --quiet

Suppresses all output during the initialization process.

Example:
```
git init --quiet
```

Using VSCode

If your workspace is on your local machine, you can enable Git source control by creating a Git repository with the Initialize Repository command. When VS Code doesn't detect an existing Git repository, the Source Control view will give you the options to Initialize Repository or Publish to GitHub.

You can also run the Git: Initialize Repository and Publish to GitHub commands from the Command Palette (Ctrl+Shift+P). Running Initialize Repository will create the necessary Git repository metadata files and show your workspace files as untracked changes ready to be staged. Publish to GitHub will directly publish your workspace folder to a GitHub repository, allowing you to choose between private and public repositories.

Clone an existing Git Repository

The git clone command is used to create a copy of a remote Git repository. It copies the entire repository, including the commit history, branches, and files, to your local machine. Here's a detailed explanation of the git clone command along with some commonly used flags and options:

1. `git clone <repository_url>`

Clones a remote Git repository to your local machine in the folder that you are in. To obtain a local copy of a project, collaborate with others, or contribute to open-source projects.

git clone <repository_url>

Example:

git clone https://github.com/example/repo.git

2. `git clone --branch <branch_name>`

Clones a specific branch from the remote repository. To clone a specific branch instead of the default branch (usually master or main).

git clone --branch <branch_name> <repository_url>

Example:

git clone --branch develop https://github.com/example/repo.git

3. `git clone --branch <branch_name> <repository_url>`

Clones a specific branch from the remote repository to a specific folder. To clone a specific branch instead of the default branch (usually master or main) into a specific folder.

git clone --branch <branch_name> <repository_url> <path/to/folder>

Example:

git clone --branch master git@github.com:ArceLopera/git_refresher.git mylocalrepo

4. `git clone --depth <depth>`

Clones a specified number of commits from the remote repository, creating a shallow clone.To reduce the size of the clone by fetching only a limited commit history.

git clone --depth <depth> <repository_url>

Example:

git clone --depth 1 https://github.com/example/repo.git

5. `git clone --recursive`

Clones submodules along with the main repository. To clone and initialize submodules contained within the repository.

git clone --recursive <repository_url>

Example:

git clone --recursive https://github.com/example/repo.git

6. `git clone --mirror`

When cloning a Git repository, only the default branch (usually main or master) is checked out by default, but all other branches are downloaded. If you want to explicitly ensure all branches are cloned and available locally, you can use the --mirror flag. This command allows you to upload your mirrored repository to another remote repository after converting it to a regular repository:

1. Mirror Clone the Original Repository

Start by creating a bare mirror clone of the original repository:

git clone --mirror <original-repository-url> repo.git

This clones the repository into repo.git, containing all branches, tags, and references.

2. Convert the Bare Repository to a Regular Repository

Navigate into the mirrored repository:
```
cd repo.git
```
Unset the bare configuration:
```
git config --unset core.bare
```

Move .git into a new working directory:

cd ..
mkdir repo
mv repo.git repo/.git
cd repo

Check out the default branch to create the working directory:
```
git checkout <branch-name>
```
Replace <branch-name> with the default branch name, such as main or master.

3. Prepare for Uploading to a New GitLab Repository

Create a New Repository in GitLab

Go to your GitLab/Github instance and create a new repository.
Copy the repository's SSH or HTTPS URL (e.g., git@gitlab.com:username/new-repo.git).

Set the New Repository as Remote

In your local repository, remove the old remote (if any):
```
git remote remove origin
```

Add the new GitLab repository as the remote:

git remote add origin <new-repository-url>

Verify the remote URL:
```
git remote -v
```

4. Push All Branches and Tags to the New Repository

Push all branches to the new repository:
```
git push --all origin
```
Push all tags to the new repository:
```
git push --tags origin
```

5. Verify the New Repository

Go to the new GitLab repository in your browser.
Confirm that all branches, tags, and files are present.

6. Optional: Set the Default Branch

In the new GitLab repository, go to Settings > Repository.
Set the default branch (e.g., main or master).

Summary of Commands

Mirror clone the original repository:

git clone --mirror <original-repository-url> repo.git

Convert to a regular repository:

cd repo.git
git config --unset core.bare
cd ..
mkdir repo
mv repo.git repo/.git
cd repo
git checkout <branch-name>

Set up the new remote:

git remote remove origin
git remote add origin <new-repository-url>

Push all branches and tags:

git push --all origin
git push --tags origin

Verify and adjust settings in GitLab.

This workflow ensures you upload a complete copy of the original repository, including all branches, tags, and history, to the new GitLab repository. this is called Mirror Clone and it is useful for maintaining an exact copy of the repository, including all refs. There is also Repository Export: Convenient for platform-managed repositories. Platforms like GitHub and GitLab provide backup or export options that include the full repository, including its .git directory.

For GitLab:

Go to the project settings.
Use the Export project feature.
Download the exported project, which includes the history.

For GitHub:

Use the Archive repository feature (if available) or manually download the .git directory.

Finally an other strategy is to use Git Bundle: Ideal for transferring repositories when direct cloning is not possible (e.g., no network access).

Starting a Project

Initialize the Git Repository

git init Options

Initialize a New Git Repository

Initialize in a Specific Directory

git init Flags

--bare

--template=<tmplt_dir>

--separate-git-dir=<git_dir>

--quiet or -q

Using VSCode

Clone an existing Git Repository

1. git clone <repository_url>

Example:

2. git clone --branch <branch_name>

Example:

3. git clone --branch <branch_name> <repository_url>

Example:

4. git clone --depth <depth>

Example:

5. git clone --recursive

Example:

6. git clone --mirror

1. Mirror Clone the Original Repository

2. Convert the Bare Repository to a Regular Repository

3. Prepare for Uploading to a New GitLab Repository

Create a New Repository in GitLab

Set the New Repository as Remote

4. Push All Branches and Tags to the New Repository

5. Verify the New Repository

6. Optional: Set the Default Branch

Summary of Commands

`--template=<tmplt_dir>`

`--separate-git-dir=<git_dir>`

`--quiet` or `-q`

1. `git clone <repository_url>`

2. `git clone --branch <branch_name>`

3. `git clone --branch <branch_name> <repository_url>`

4. `git clone --depth <depth>`

5. `git clone --recursive`

6. `git clone --mirror`