Contents
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.
An example of the process would be:
./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!
Note that some operating systems and Linux distributions require that you add additional options to configure for it to work properly. Configure works without arguments on only a few distros.
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.
A README.GIT.md file exists in the source tree that contains very basic git usage instructions, just as there used to be a README.CVS.
For Developers
Please see README.GIT.md and README.developers.md on the Xastir github page for developer-specific guidance.
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
If you intend to develop code for Xastir, 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