Git Instructions
For Users
Install and Configure Git
To get a copy of the development repository, you must have "git" installed on your system.
git --version
will let you know if you have it installed. If not, install it!
The "git config" commands below are not strictly necessary, but if you ever try to make changes to Xastir and get them integrated with the project, the first command listed is quite important. The email address should correspond to the address associated with your GitHub account, but you don't need an account until you are a contributor to the project, or any GitHub project. Colorizing the Git output and having it ignore whitespace are niceties.
git config --global user.name "Your Name" user.email "Your@email.address" git config --global color.ui auto git config --global core.whitespace "-trailing-space"
Getting the Source Code
To obtain the Xastir repo for the first time:
git clone https://github.com/Xastir/Xastir
This will create an "Xastir" subdirectory, put a complete clone of the repository into it (including ALL branches and revisions!), and check out the "master" branch of the code.
Compiling and Installing Xastir
Then configure/compile/install normally. Make absolutely certain you have installed all prerequisite tools and libraries first. See System Requirements for the details. If, at any point, you see error messages in the steps below, you have missing required packages. There is no point working through all the steps if you see error messages early on. Notably, bootstrap.sh requires autoconf and automake, and this script is what produces the configure script used later. If bootstrap.sh fails fails nothing will work. If you don't have Motif headers and libraries installed, configure will abort. Double check the requirements page, fix missing package issues, and start again.
./bootstrap.sh
mkdir -p build # Build in a separate directory
cd build
../configure
(make clean;make -j3 2>&1) | tee make.log
sudo make install # "make install-strip" can be used after the first
# time: It removes debugging info from executable
sudo chmod 4555 /usr/local/bin/xastir # Only needed if using kernel AX.25
xastir & # Start it up!
Updating Your Copy
Periodically, you can update the code by going into the repo directory and executing:
git pull
then compiling normally per the "Compiling and Installing Xastir" instructions shown above. Note to developers only: "git pull" is risky for you if you are modifying code.
-OR- you can type:
./update-xastir
which will do EVERYTHING for you from the "git pull" to the "chmod" command. This will work if you don't need to pass any extra flags to "configure" for your particular Linux. Note to developers only: "./update-xastir" is risky for you if you are modifying code: It uses "git pull".
If you intend to contribute code to the Xastir project, there's going to be more to learn, but if you only want access to the latest sources, these few Git commands will be sufficient.
A new README.GIT file exists in the source tree, just as there had always been a README.CVS.
For Developers
Make sure you've configured Git as shown above, particularly the name and email address commands. The email address should correspond to the address associated with your GitHub account. If you already have a global address set up for other purposes, you may want to set a local config once you clone the Xastir repo: See the section "If Using Multiple GitHub Accounts" below.
Initial Checkout
HTTPS Method:
git clone https://github.com/Xastir/Xastir
-or-
SSH Method. Add keys to GitHub and then:
git clone git@github.com:Xastir/Xastir
Note that using the SSH method means that you won't have to answer the popups for user/password each time you do anything with the remote repo, although you will have to answer with a passphrase if you added one to your SSH key. The SSH method is highly recommended for active developers!
Normal Development Flow
A "git pull" before committing can be dangerous if there are substantial conflicts between your work and others (not very likely with Xastir, but definitely likely in bigger projects). It is much better to do a "git fetch" (which pulls down changes from the remote but DOESN'T merge them into your tracking branch), look at what changed upstream, then perform a "merge", "rebase", "stash"/"pop", or something else depending on the level of conflict you see. See README.GIT.
Doing a "git pull" before starting your own work is reasonable, but if someone does a "git push" while you're working (again, not very likely with Xastir), you can still wind up with really ugly history, with weird merge commits and undesired branching.
On the other hand, if you replace "git pull" with "git pull --rebase" in that recipe, with the caveat that sometimes you might have to be more careful and that you need to understand what you're doing, a lot of the danger of the simple "git pull" can be avoided.
We will often be working on a branch for development, then merging that branch with the trunk when that feature or bug-fix is ready for prime-time.
Add new or changed files to the staging area:
git add <file1> <file2>
Commit your work to your LOCAL repo:
git commit
Push your local repo changes up to GitHub:
git push
Important: Git Commit Message Format
Git commit messages need to be in a certain format to make the best use of the "git log" commands. In particular the first line needs to be 50 chars or less, then a BLANK LINE, then a detailed commit message. See this link for more info:
How to Write a Git Commit Message
Checking Out A Branch
All branches associated with the Xastir project are contained in the clone you made earlier. You can switch your current working directory to one of those branches easily:
cd Xastir
git fetch (this updates your local repo copy from github, but doesn't
merge changes into your working tree)
git checkout <branch name> (this switches all the files in your working
tree to match those in the branch)
git merge (This makes sure that all the changes that
may have happened upstream on that branch
get into your copy)
You do not have to do this in a new directory --- so long as you haven't changed any files in the source tree, git checkout automatically swaps out all files it knows about with versions from the branch.
If you really want to keep more than one branch's code around to work on, you can do that if you have git version 2.5 or later with the following commands:
cd Xastir git worktree add <path> <branchname>
This will create a new directory tree called <path> with the named branch checked out into it.
At the time of this writing there were only two branches in the Xastir repository: "master" (the primary Xastir project) and "BRANCH_qt".
The Qt Branch
There is currently only one non-default branch in the Xastir repository and contains an experimental Qt-based version of Xastir: "BRANCH_qt".
You can check it out according to the instructions above.
Latest Qt status: The File->Exit and Interface->Interface Control portions work, but none of the other menu options have been implemented. It will display raw packets as they come in but there are no maps, symbols, etc. The networking is both IPv4 and IPv6 compatible.
NOTE: "BRANCH_qt" was merged with the "master" branch July 12, 2016. Refer to "README.qt" for instructions on building the Qt version.
If Using Multiple GitHub Accounts
You may have trouble getting your commits attributed to the correct GitHub login. GitHub uses the username/email in your git config settings for attribution. If it is wrong, you may have to do some of the below in order to set a LOCAL username and email for the one repository.
The user.name and user.email are pulled from the global git config, but a local git config inside each repo will override those settings. Note that NOT specifying "--global" means you're setting a LOCAL variable which will only take effect inside the repository you're in when you issue the command. You can also specify "--local" in the command to make that explicit.
Go to root of checked-out repo and set local user.name and user.email for this repo:
git config user.name <github username> git config user.email <email address> git config -l # Shows both local and global settings, hard to tell which is which git config --global # Shows global settings git config --local -l # Shows local repo configs, so should show new settings
Another method (but more error-prone) of editing local/global git config is:
git config edit # Edit local config git config --global edit # Edit global config
If new commits still aren't using the right email, make sure you have not set GIT_COMMITTER_EMAIL or GIT_AUTHOR_EMAIL environment variables.
More Info
Make sure you know how git works. Read https://git-scm.com/book/en/v2
If you are very familiar with CVS, get used to working differently, because git is different.
Read and understand http://chris.beams.io/posts/git-commit/
Read http://justinhileman.info/article/changing-history/
Read http://think-like-a-git.net/
Read "Visual Git Cheat Sheet" at http://ndpsoftware.com/git-cheatsheet.html
Branching and merging in git is very simple, and is documented very well by all those links. We will not repeat it here.
Useful Git Commands
Set up global user/email
git config --global user.name "Your Name"
git config --global user.email "user@domain.com"
Set up user/email for a local repository
cd /path/repository
git config user.name "Your Name"
git config user.email "user@domain.com"
Configure Git's editor:
git config --global core.editor /path/to/editor
Colorizing Git output (set once and forget):
git config --global color.ui auto
Getting rid of white-space warnings:
git config --global core.whitespace "-trailing-space"
Clone a repo:
git clone http://github.com/Xastir/Xastir git clone https://github.com/Xastir/Xastir git clone git@github.com:Xastir/Xastir
Status of local repo:
git status
Diff for a file:
git diff <filename>
See all branches, local and remote:
git branch -a
Visual Git viewer:
gitk (tcl/tk and generic X11 viewer, comes with git)
GitX (OSX viewer)
gitg (gnome git viewer)
-or- git log --oneline --abbrev-commit --all --graph --decorate --color
Add new or changed files to the staging area:
git add <file1> <file2>
Commit changes to LOCAL repo:
git commit
git commit <file1> <file2>
Push local changes to remote repository:
git push
Update local repo from remote repo
git fetch
Update local repo and merge remote/local changes in local repo:
git pull
Rebase local changes against latest master branch
git fetch
git rebase master
Copyright© 2016 The Xastir Group