Add gitignore to checkin with overwrite protection, update README

Author: artvvb

README.md

@@ -4,15 +4,15 @@ This repository contains a set of scripts for managing Vitis workspaces with git
 ----
 ## Quick Checkout Guide
 
-To clone a repository using these scripts as a submodule (referred to as the parent repository), either clone the parent repository recursively (`git clone --recursive <URL>`), or initialize and update the repository's submodules after cloning (`git submodule update --init` within the repo directory). This is required in order to ensure that submodule sources are fully downloaded, and that the correct versions of those sources are used.
+When cloning this repository, use the command `git clone --recursive <URL>` to pick up any submodules this repository may use to bring in additional source files. Alternatively initialize and update the repository's submodules after cloning (`git submodule update --init` within the repo directory).
 
-Some Digilent Github repositories that use this as a submodule also require that you check out a specific demo branch. In these cases, refer to the parent repository's documentation for additional instructions, upon checking out a demo branch, submodules should be reupdated and reinitialized (`git submodule update --init`, as above).
+Some Digilent Github repositories also require that you check out a specific demo branch. Whenever checking out a demo branch, submodules should be reupdated and reinitialized (`git submodule update --init`, as above).
 
-When launching Vitis, whether through Vivado's *Tools* menu, or on its own, the Vitis workspace should be the parent repository's sw/ws folder.
+When launching Vitis, whether through Vivado's *Tools* menu, or on its own, the Vitis workspace should be set to the repository's sw/ws folder.
 
 The scripts present in this repository can be run through the use of the Xilinx Software Command-Line Tool (XSCT), which is built into Vitis. This tool can be opened within the Vitis GUI through the *Xilinx > XSCT Console* option in the menu bar at the top of the window. Upon launch, XSCT's current working directory is set to the Vitis install directory. To recreate the workspace, enter the following command into the XSCT Console:
 
-`source [getws]/../scripts/checkout.tcl`
+`source [getws]/../src/checkout.tcl`
 
 This process will populate the workspace with projects containing sources from the parent repository's src folder, configure those projects, and fully build them. This may take several minutes to fully complete. When the script is finished running, the `xsct%` prompt wil reappear in the tan XSCT Process pane. From this point, the demo can be programmed onto a board, sources can be viewed, and modified, as desired.
 
@@ -21,7 +21,7 @@ This process will populate the workspace with projects containing sources from t
 ----
 ## Quick Checkin Guide
 
-**Important:** *The checkin.tcl script should generally only be used for the first time checking a project into version control. For further commits, files should be manually moved into the repository's src directory. Application source files (and linker scripts) are soft-linked into the workspace upon checkout, so existing files do not need to be manually copied back.*
+**Important:** *The checkin.tcl script should generally only be used for the first time checking a project into version control. For further commits, new files should be manually copied into the repository's src directory. Application source files (and linker scripts) are soft-linked into the workspace upon checkout, so existing files do not need to be manually copied back. Modifications to project settings require that the corresponding scripts in the repository's src directory be edited.*
 
 This section assumes that you have already created a Vitis workspace containing one or more application projects. Some additional work may be required after the checkin script is completed, and it is important that you try the checkout process afterwards to ensure that all important settings are properly included.
 
@@ -37,6 +37,7 @@ Open your workspace in Vitis. Open the XSCT Console from within the Vitis GUI by
 
 This script will create a src directory in the same folder as the scripts submodule, and populate it as below:
 
+* checkout.tcl script and README file
 * One folder per application project, containing the following:
   * A src directory, containing the application project's local sources (from its src folder) and linker script.
   * A #_standalone_app.tcl script, containing the XSCT commands required to recreate and configure the project.
@@ -47,6 +48,8 @@ This script will create a src directory in the same folder as the scripts submod
   * A #_hw_pf_xsa.tcl script, containing the XSCT commands required to recreate and configure the platform, using only the XSA as input.
   * The XSA file describing the hardware specification that the software targets, exported from Vivado.
 
+Additionally, a gitignore file is created in the parent repository's sw directory.
+
 Note that the name of each folder is used in checkout to determine the name of the app/platform/domain it is used to create.
 
 The numeric prefixes for XSCT scripts are used to determine the order in which they are sourced during checkout (lowest to highest). Recommended: 0-9 for hardware platform, 20-29 for bsp, 40-49 for app creation. Build scripts are recommended to use > 100.

checkin.tcl

@@ -346,7 +346,7 @@ foreach app_name $app_names {
 			if {[file exists $dest_dir/$app_name/src] == 0} {
 				file copy -force -- $appsrc_path $dest_dir/$app_name
 			} else {
-				puts "WARNING $dest_dir/$app_name/src already exists; cannot copy source directory"
+				puts "WARNING: $dest_dir/$app_name/src already exists; cannot copy source directory"
 			}
 		} else {
 			puts "file copy -force -- $appsrc_path $dest_dir/$app_name"
@@ -391,4 +391,22 @@ if {$debug_prevent_fileio == 0} {
 	file copy -force -- [file normalize $script_dir/sub/cleanup._cmd] [file normalize $dest_dir/../ws/cleanup.cmd]
 }
 
+# Copy template gitignore
+if {$debug_prevent_fileio == 0} {
+	set gitignore [file normalize $dest_dir/../.gitignore]
+	if {[file exists $gitignore] == 0} {
+		set copy_ok 1
+	} else {
+		set input [yes_or_no "WARNING: $gitignore exists, overwrite it? (y/n):"]
+		if { [string equal -nocase -length 1 $input "n"] } {
+			set copy_ok 0
+		} else {
+			set copy_ok 1
+		}
+	}
+	if {$copy_ok} {
+		file copy -force -- [file normalize $script_dir/sub/template.gitignore] $gitignore
+	}
+}
+
 puts "INFO: Checked in workspace [getws] to $dest_dir"

sub/template.gitignore

@@ -0,0 +1,5 @@
+# ignore everything in workspace dir
+ws/*
+# except the cleanup scripts
+!ws/cleanup.cmd
+!ws/cleanup.sh