Contents x
Git 101 - Git overview
  • 5 Minutes to read
  • Print
  • Dark
    Light
  • PDF
Contents

Git 101 - Git overview

  • 5 Minutes to read
  • Print
  • Dark
    Light
  • PDF
Article summary

Git 101: What is Git?

Git is a magic tool to help you track, version, and release your files.

It is easy to learn everything you need to know for day-to-day tasks, and powerful enough for automation.

Git runs on our AllSpice server and on your local machine.

Track your design changes

Artboard 1 copy 4git slides.png

  • Change from main to develop branch
  • Create design changes on their local file system
  • Commit the files to their local develop branch
    • Add a meaningful commit message
    • "Remove C237, 0.2uF bypass cap from U14
  • Commits are pushed to remote branch

Review your design changes

Artboard 1 copy 5git slides.png

  • Create a Design Review to merge develop branch to main branch
  • Team reviews changes
    • Suggest/require changes
    • Review fabrication/output files
    • Create Issues to resolve/defer action items
    • Approves design review by merging develop branch to main

Git 101: Installing Git

your title goes here

Full article on installing Git

If you've never used Git before, then we recommend GitHub Desktop for ease of use. Your teammates might make a recommendation

Git 101: Branches

Branches organize and control change

Changes are first committed to a local branch and then are pushed to a server. Changes can't move from one branch to another without using a design review, or by manually adding them.

We recommend a two-branch strategy for hardware development.
- Main branch alway is the latest release
- Releases for V1, V2...VN
- Develop branch contains proposed changes
- All developers work on the same branch

Branch protection allows you to prevent accidental pushes or merges.

  • Visit your repository settings

    • Click on the Branches menu

    • Click on "Add New Rule" to add a new rule

    • Screenshot 2024-01-11 at 1.14.25 AM.png

    • Add the name of the branch you would like to protect and configure the settings.

    • We recommend disabling push

    • Screenshot 2024-01-11 at 1.17.01 AM.png

Git 101: Design reviews

Design reviews

Full article on Design Reviews

Git Design Reviews allow you to verify the file changes before you merge one branch to another. It is the equivalent to an ECO.

image.png

AllSpice.io Design Reviews are Git Pull Requests (PR) with a name more familiar to electrical engineers

Design review interface

Design Reviews have 3 main tabs

  • Design Review interface
    • Screenshot 2024-01-11 at 1.25.10 AM.png
  • Conversations
    • Reviews
    • Requests for change
    • Comments or instructions
    • Request for investigation
  • Commits
    • Serial list of all changes
  • Files Changed
    • Visual diffs of PCBs, Schematics, BOMs, and any text files

Creating a Design Review

  • Visit your repo
  • Click on the Design Reviews Tab
  • Click on New Design Review
    • image.png
  • Select the pull-from branch on the right. This is usually develop
    • image.png
  • Ensure the branch on the left is your target branch. This is usually main.
  • Click New Design Review
    • image.png
  • Enter a name or title for your review
  • You can create a Design Review template that will pre-populate the description with useful information and checklists. To learn more visit the main article.
  • Add any Labels needed to categorize the review
  • Attach milestones to track your repos
  • Once everything looks ready, click Create Design Review
    • image.png
  • Add Reviewers who will approve and be able to comment
    • image.png

Design Review Visual Diff (Files Changed)

The Files Changed Tab helps you review your changes.

  • Screenshot 2024-01-11 at 1.38.41 AM.png

On the left is a file tree showing which files are new, which have changes, and which have been deleted.

The file diffs are on the right.

You can create snippets to communicate any requested changes.

  • View your schematic or PCB
  • Click on Snippet
  • Highlight the section you wish to show
  • Click the "+" button
  • Add your custom message
  • Click "Add single comment"
    • snippet.gif

To learn more Full article

Git 101: Issues

Issues are the equivalent of Action Items. You can use them to highlight work that needs to be done immediately, or use it to track work done over time.

You can attach files and have a full conversation about the issue. You can gate Deisgn Reviews from completing until certain issues have been closed.

You can create multiple issue templates and create custom interfaces.

Creating an issue

  • Visit your repo

  • Click on issues

  • Click new issues

  • If you have multiple issue templates, select your template

  • Fill out the issue

  • Assign Assignees, add labels, attach to milestones

  • @mention your teammates
    lib issue.gif

    • How do you use them

Git 101: Milestones

Please visit our main article on Milestones

Markdown

Markdown is a lightweight markup language with plain-text formatting syntax. Its main goal is to be easy to read and write, even when not converted to HTML. This article is written in markdown.

Visit our full markdown guide

Releases

See our full article on releases

Generating a Personal Access Token (PAT)

You will need to either use SSH or use a PAT to access AllSpice if you are using external authentication or SSO.

How to create an AllSpice authentication application access token

Git 102: Basic Git commands

We have a Git cheat sheet with more commands.

Copy entire remote repo to current directory
git clone [url]
Fetch and merge any commits from the tracking remote branch
git pull
Transfer your local branch commits to the remote branch repo
git push [alias] [branch]
Switch to another branch and check it out to your current working directory
git switch
Show modified files in your working directory. These files are staged for your next commit
git status
Add a file as-is to your next commit, aka stage the file
git add [file/directory]
Commit your staged files as a new commit
git commit -m "[descriptive message]"

Writing a good commit message

- Short (Under 60 characters)
- Descriptive (what did you do?)
- This will be part of the review
- Use imererative tense
- Add bypass cap
- vs "Added bypass cap"

Git 102: Merge conflicts

Merge conflicts happen when two different people make changes to files on either the same branch, or different branches. When they go to merge, there will be a merge conflict.

Avoiding merge conflicts

The best way to deal with merge conflicts is by prevention.
- Set up branch protection on main
- Separate schematics into multiple files
- Communicate when working on single files like the PCB
- Use LFS to lock files

Fixing merge conflicts

Although we're building a merge engine, for now, the best way to fix a merge conflict is to view the file changes in AllSpice and manually copy the changes to the new file.

Teams and role-based permissions

Visit our main article on teams

Was this article helpful?
What's Next
Accelerate your time to market with AllSpice - enabling modern revision control and collaboration for native electronic designs
Products
Company
Existing Users
Connect With Us