<cat>Hammer.Advanced</cat> Please note that right now this article assumes a lot of knowledge, and I hope to fix that with feedback and other community contributions over time. Right now this is a decent starting point while we figure out and refine our workflows between one another. This article will use terminal based git commands, because these can be easily translated back into other git GUI/software of your choosing. ## Quick and dirty guide to git If you don't already have Git LFS installed for your repository, you're going to need it. Read more about it [here](https://git-lfs.com/). Git is a tool that helps track changes to a project, typically code, and provides a powerful set of tools for managing different versions of the project as well resolving conflicts that may arise when multiple developers are working on the same project. ### The Main branch. The main branch is typically reserved for the most stable and working build of the project. This is because the main branch represents the current state of the project that is ready to be released or deployed. It is important to ensure that the main branch is always in a stable state, so that it can be used as a reliable foundation for not just future development, but releases and issues. ### The Development Branch The development branch is a separate branch that is used for ongoing development work. It is the branch where all new features, updates, and fixes are developed and tested before they are merged into the main branch. The development branch should be the source of truth for all development, as it allows for a clear separation of work in progress from the stable main branch. By using a separate development branch, you can ensure that changes are fully tested and reviewed before they are merged into the main branch. Using the development branch as the source of truth also helps to avoid conflicts and issues that can arise when multiple developers work on the same project simultaneously. Each developer can work on their own branch off of the development branch, and once their work is completed and reviewed, it can be merged back into the main branch. ### Team Member Branches To work on their own features or assigned work, team members will branch off of the development branch using their own name initially. For example, Aleph will branch off the development branch, naming their branch "aleph". Though this isn't required it might make things easier for people new to git to get organized. ### Feature Branches After The team member should then create a separate branch for their assigned work, such as a prefab, and name it accordingly. For example, Aleph has been assigned to work on a prefab called "`house01_1`", so they can create a new branch off of their own branch, naming it "`house01_1`". See the section on "Prefab Assignment" below for more information. ## Git and Hammer workflow In our Hammer level design workflow, the development branch will contain the main .vmap file, which is the main level file. Each team member will create a separate branch off of the development branch, which they will use to work on their assigned prefab during the block-out phase. ### The Block-out Phase After the initial block-out phase, each section or objects within a section that will be distributed for work by other team members will need to be made into a prefab. **This is the last time you will touch the main level's .vmap on this branch until it's time to review all changes together.** #### Prefab Assignment Team members will be assigned specific area of the map or object to work on so that they have a clear responsibility. One way to manage these assignments in a git workflow is to make each object or area of the map into a prefab. These prefabs can then be assigned to individual team members for them to work on. When a team member is assigned a prefab, they can create a new feature branch and work out of that. **team members should only make changes to their prefab**, no one else's. This can cause conflicts down the line if someone else's prefab is changed and you're merging your changes into the development branch. Once the work on the prefab is complete, the team member should create a pull request to merge their changes back into the main development branch. This pull request can then be reviewed by other team members, who can provide feedback or make suggestions for changes. Prefab changes are reflected almost instantly in Hammer, assuming that it already exists within the main level file. ## Git commands and configuration ### .gitignore File After creating and checking out their branches, each team member should create a .gitignore file and add the following: ``` *.vpk *.los *.dmx mainMapFile.vmat ``` ### .gitattributes (lfs) The .gitattributes file is so that LFS tracks which non-source code files to track. In this case I have everything from .png's to .vmats. ``` *.png filter=lfs diff=lfs merge=lfs -text *.vmat filter=lfs diff=lfs merge=lfs -text *.jpg filter=lfs diff=lfs merge=lfs -text *.vmap filter=lfs diff=lfs merge=lfs -text *.vmat_c filter=lfs diff=lfs merge=lfs -text *.vmap_c filter=lfs diff=lfs merge=lfs -text *.vtex_c filter=lfs diff=lfs merge=lfs -text *.tga filter=lfs diff=lfs merge=lfs -text *.vpcf_c filter=lfs diff=lfs merge=lfs -text *.vpcf filter=lfs diff=lfs merge=lfs -text ``` ### Git Commands Setting up the development branch: ``` git checkout -b dev-0.1 main ``` Team Member Branches: ``` git checkout -b myname dev-0.1 ``` Committing Changes: ``` git add . git commit -m "Updated myprefabname" ``` Pushing committed changes to remote: ``` git push origin myfeaturename ``` Merging Changes: ``` git checkout myname git merge myfeaturename ``` ⤶ Pull Requests: ```⤶ Create a pull request on Github. Add a title and comment. Press the Create pull request button.⤶ Wait for team members to review⤶ ```⤶ ⤶ #### Pushing huge changes Note:⤶ ⤶ ### Pull Requests: ⤶ 1. Create a pull request on Github.⤶ 2. Add a title and comment. 3. Press the Create pull request button. 4. Wait for team members to review⤶ ⤶ ⤶ #### Pushing huge changes Note:⤶ If your project is huge, you're going to have to make your changes in pieces, your remote pushes can timeout if you're pushing something over 5 gigs. Use your .gitignore to break your project up into smaller pieces. Remove file paths & extensions from .gitignore as you're ready to push them. Keep it small, git hates large files, and it hates files that aren't code so it's actively working against you.