Complete GIT Guide – Best Practices with GIT

Descriptive commit messages

Commit messages are a crucial part of your GIT history, acting as a narrative of your project’s evolution. A good commit message not only describes what changes were made, but also why they were made, providing valuable context for you and other developers in the future.

Why are descriptive commit messages important?

• Understanding the history: They make it easier to understand the changes made in the project, allowing other developers (and even yourself in the future!) to understand the reasoning behind each decision.
• Effective collaboration: Help team members stay on top of changes and understand the context of each other’s contributions.
• Debugging and troubleshooting: Enable tracking the introduction of bugs or problems by identifying the commits that may have caused them.
• Documentation generation: They can be used to automatically generate changelogs (changelogs) and other project documentation.

Features of a good commit message:

• Concise and clear: Describes changes briefly and directly, using simple and understandable language.
• Present and imperative verb: Use the present indicative in imperative form to describe the action taken (e.g., “Add ‘, ’Correct ‘, ’Improve ”).
• Emphasis on change: Focus on what has been changed, not how it has been done. Avoid unnecessary technical details in the main message.
• Context and motivation: Briefly explain why the change was made, what problem it solves or what functionality it adds. You can include more details in the body of the commit if necessary.
• References to issues or tasks: If you are working with a task or issue tracking system, include references in the commit message for easy traceability.

Examples of good commit messages:

• Good: “Add contact form validation.”
• BAD: “Changes in the form.php file”.
• Good: “Fixes calculation error in function calculate_taxes”
• Bad: “Fixed a bug”.
• Good: “Improved performance of database query using indexes”
• Bad: “Code optimization”.
• Good: “Implemented new search functionality (refs #123)”
• BAD: “Commit of new functionality”

Additional tips:

• Limit the length of the first line: The first line of the commit message should be short (ideally less than 50 characters) so that it is easy to read in the git log output.
• Use the commit body for details: If you need to provide more context or explanations, use the commit body to add additional details. Leave a blank line after the first line to separate the summary from the body.
• Style conventions: Consider adopting a style convention for commit messages, such as Conventional Commits or whatever suits your team.
• Check your messages before committing: Take a moment to review your commit messages before finalizing them. A little extra effort can make a big difference in the clarity and usefulness of your GIT history.

Common Workflows

Workflows in GIT define how development teams collaborate and manage changes in a project. Below, we describe some of the most common workflows and their key features:

1. Centralized Workflow.
   • Structure: A central repository acts as the single source of truth. Developers clone the repository, work on their local copies and push their changes (push) directly to the main branch (master or main).
   • Advantages: Simple and easy to understand, ideal for small teams or simple projects.
   • Disadvantages: Can generate frequent conflicts if several developers work on the same part of the code at the same time.
2. Feature Branch Workflow (Feature Branch Workflow)
   • Structure: Each new feature or bug fix is developed in a separate branch (feature/* or fix/*). Once completed and reviewed, the branch is merged (merge) into the main branch.
   • Advantages: Allows parallel development, facilitates code review and keeps the main branch clean and stable.
   • Disadvantages: Can generate a complex commit history if there are many branches and frequent merges.
3. Gitflow Workflow.
   • Structure: Defines a set of branches with specific roles: master or main (release versions), develop (ongoing development), feature/* (new features), release/* (release preparation), hotfix/* (urgent fixes).
   • Advantages: Provides a clear structure for large and complex projects with multiple releases and versions.
   • Disadvantages: Can be complex to understand and manage, especially for small teams or simple projects.
4. Forking Workflow.
   • Structure: Each developer has their own fork (copy) of the main repository. Changes are developed in branches within the fork and then proposed to the main repository via Pull Requests.
   • Advantages: Ideal for open source projects, allows external contributions without giving direct access to the main repository.
   • Disadvantages: May require more steps and coordination to integrate changes into the main repository.

Choosing the Right Workflow:

The choice of workflow depends on project size, team complexity, and development preferences. Consider the following factors:

• Team size: Simpler workflows may be sufficient for smaller teams, while larger teams may benefit from more formal structures such as Gitflow.
• Project complexity: Large, complex projects with multiple releases and versions may require a more structured workflow such as Gitflow.
• External collaboration: If you expect contributions from external developers, the Forking workflow may be the best option.
• Team culture: Tailor the workflow to your team’s preferences and way of working.

Using .gitignore to exclude files

The .gitignore file is an essential component to keep your GIT repository clean and organized. It allows you to specify which files or folders you want to exclude from version control, preventing GIT from tracking them and including them in your commits. This is especially useful for ignoring temporary files, environment-specific configuration files, automatically generated files, and other files that are not part of your project’s source code.

Why use .gitignore?

• Avoid unnecessary commits: Prevent irrelevant or temporary files from being included in your commits, keeping your repository history clean and focused on important code changes.
• Protect sensitive information: Allows you to exclude configuration files that contain passwords, API keys or other confidential information that should not be shared publicly.
• Enhance collaboration: Avoid conflicts and confusion by excluding files that are specific to each team member’s development environment.
• Optimize repository size: Exclude large or automatically generated files that are not necessary for building or running the project, reducing repository size and speeding up GIT operations.

How to create and use .gitignore:

• Create the file: In the root of your repository, create a text file named .gitignore (be sure to include the period at the beginning).
• Add exclusion patterns: Inside the .gitignore file, type the file or folder patterns you want to exclude, one per line. You can use wildcards (*) and other special characters to create more flexible patterns.
• Save the file: Save the changes to the .gitignore file.
• Commit the file: Use git add .gitignore and git commit -m “Add .gitignore” to include the file in your repository.

Examples of exclusion patterns:

• *.log: Ignore all files with extension .log.
• node_modules/: Ignore the node_modules folder and all its contents.
• temp/*: Ignores all files inside the temp folder.
• config.local.php: Ignores a specific file named config.local.php.
• !config.example.php: Does not ignore the file config.example.php, even if it matches other exclusion patterns.

Tips:

• Wildcards: Use (*) wildcards to create more general patterns. For example, *.tmp will ignore all temporary files with any name but with the extension .tmp.
• Negation: Use ! at the beginning of a pattern to include a file or folder that would otherwise be excluded.
• Comments: Use # at the beginning of a line to add explanatory comments to your .gitignore file.
• Templates: You can find .gitignore templates for different programming languages and frameworks online, which will save you time and effort when creating your own file.