Git version control features a branching model to track code changes. All Git repositories have a base branch. Many projects prefer to use main as the name of the base branch. When you create a commit in your repository, the base branch is updated with the new commit. Git uses the term HEAD to describe the pointer to where you are in the currently active branch.

Figure 3.4: Commits to the main branch of a Git repository.

By convention, the main or master branch in a Git repository contains the latest, stable version of the source code. To implement a new feature or functionality, create a branch from the main branch. This new branch, called a feature branch, contains commits corresponding to code changes for the new feature. The main branch is not affected by commits to the feature branch.

Figure 3.5: Commits to a feature branch of a Git repository.

When you use a branch for feature development, you can commit and share your code often without impacting the stability of code in the main branch. After ensuring that the code in the feature branch is complete, tested, and reviewed, you are ready to merge the branch into another branch, such as the main branch. Merging is the process of combining the commit histories from two separate branches into a single branch.

Figure 3.6: Merging a feature branch into the main branch.

Git has sophisticated mechanisms to merge code changes from one branch into another branch. However, if there are changes to the same file in both branches, then a merge conflict can occur.

A merge conflict indicates that Git cannot automatically determine how to integrate changes from both branches. When this happens, Git inserts markers in each affected file to indicate the sections that contain content conflicts from both branches.

Figure 3.7: Viewing a merge conflict in VS Code.

For each conflict in a file, replace the content between the merge conflict markers (<<<<<<<< and >>>>>>>> inclusive) with the correct content from one branch or the other, or an appropriate combination of content from both branches.

You can also click Resolve in Merge Editor and resolve the merge conflict there.

Figure 3.8: Resolving a merge conflict in VS Code.

After you reconcile the content for each conflict in a file, you need to save, stage, and commit the file changes. You can then synchronize with the remote repository.

Different branches in Git enable different work streams to evolve in parallel in the same Git repository. Commits for each work stream append only to that branch.

From the command line, you can use the git branch command to create a branch from the current HEAD commit. This command creates a reference for the new branch, but it does not set the current HEAD to this branch. Use the git checkout command to move the HEAD to the appropriate branch.

To create a branch in VS Code, click the Source Control icon in the left navigation menu, or click View → Source Control to display the Source Control panel. Click the Views and More Actions icon (…​) and then click Branch → Create Branch.

Figure 3.9: Creating a new branch in VS Code.

Part of the point of a version control system is to track a history of commits. A commit hash identifies each commit.

The git log command displays the commit log messages with the associated ID hashes for each commit.

The git show commit-hash command shows what was in the change set for a particular commit hash. You do not need to use the entire hash with this command; only enough of it to uniquely identify a particular commit in the repository. These hashes can also be used to revert to earlier commits or otherwise explore the version control system's history.

Ansible Roles and Ansible Content Collections are ways that you can reuse code from other Ansible projects.

You can include roles and Ansible Content Collections in your Ansible project's Git repository. In this case, each collection is generally stored in subdirectories of the collections/ directory, and each role is stored in subdirectories of the roles/ directory.

There might also be a requirements.yml file in either or both of those directories that specifies collections or roles that are used by this project.

A role or collection can have its own Git repository. Then instead of keeping a copy of the role or collection in your Ansible project's repository, automation controller can retrieve it directly from the relevant role or collection repository when it runs playbooks that belong to the project.

To set this up, create requirements.yml files in your roles/ and collections/ directories. Then use the ansible-galaxy command to populate this directory with the latest version of roles from automation hub, Ansible Galaxy, or their Git repositories before you run the project's playbooks.

Not every file and directory in your Ansible project directory should be tracked by Git. You can configure Git to ignore files and directories that should not be tracked or committed.

To configure Git to ignore specific files and paths in your project, add a .gitignore file at the top of your Ansible project directory.

Each line in a .gitignore file represents a pattern to match, and that determines whether Git ignores a file in the repository. Generally, lines that match file names indicate files that Git ignores. Lines that start with an exclamation mark (!) indicate files that Git should not ignore, even if they were matched by a previous pattern. You can use blank lines to improve readability, and any line that starts with a number sign (#) is a comment.

Details on the pattern matching format for this file are documented in the gitignore(5) man page under "PATTERN FORMAT". Pay particular attention to the distinction between single asterisks (*) and double asterisks (**) in these pattern matching lines. (Double asterisks can match multiple directory levels.)

For example, if you use requirements.yml files with the ansible-galaxy command to populate the project's roles and collections directories, then you should configure Git to ignore the populated content.

A sample .gitignore file might contain the following content:

roles/**
!roles/requirements.yml
collections/ansible_collections